AGENTS.md

1# Working in this repository
2 
3<!-- Generated by scripts/sync_style.py from CLAUDE.md. Do not edit this file. -->
4 
5This repository ships one output style to seven coding agents. One file is
6canonical. Everything else is generated from it or checked against it.
7 
8Read this before you edit anything here.
9 
10## The one rule that breaks the build
11 
12Edit [`output-styles/attention-control.md`](./output-styles/attention-control.md).
13Never edit a generated file.
14 
15These files are generated. Each carries a "Do not edit this file" marker:
16 
17| Generated file | Built from |
18|---|---|
19| `skills/attention-control/SKILL.md` | the canonical style |
20| `.cursor/skills/attention-control/SKILL.md` | the canonical style |
21| `.cursor/rules/attention-control.mdc` | the canonical style |
22| the snippet section of `INSTALL.md` | the canonical style |
23| `AGENTS.md` | `CLAUDE.md` |
24 
25`AGENTS.md` and `CLAUDE.md` say the same thing. Edit `CLAUDE.md` and run the
26generator; the mirror follows.
27 
28## Which file your tool reads
29 
30| Tool | Reads | For |
31|---|---|---|
32| Claude Code | `CLAUDE.md` | these standards |
33| Cursor | `AGENTS.md` and `CLAUDE.md`, both automatic | these standards |
34| Gemini CLI | `AGENTS.md`, then `GEMINI.md` | these standards, then the style |
35| Any other agent-instruction harness | `AGENTS.md` | these standards |
36 
37`GEMINI.md` is not a repository guide. `gemini-extension.json` names it as the
38extension's context file, so it is what a Gemini CLI user gets when they
39install this style. Leave it as the style.
40 
41`.gemini/settings.json` adds `AGENTS.md` to the context list, so a Gemini agent
42working here reads the standards and the style. It changes nothing for anyone
43who installs the extension.
44 
45After any edit to a source file, run:
46 
47```bash
48python3 scripts/sync_style.py
49```
50 
51CI fails when a copy drifts. `scripts/sync_style.py --check` is the gate.
52 
53## Write in the style you are editing
54 
55This repository uses its own output style. Apply it to your responses and to
56the prose you write into these files.
57 
581. Lead with the next action. A command, a path, or a snippet goes first.
592. Do the work you own. Never hand back a step you can finish yourself.
603. Give the runnable thing. "Run the migration script" is a label. The path or
61   the snippet is an action.
624. Never invent a specific. A version, a date, a flag, or a line number you
63   cannot check is a fabrication, whatever tone you write it in.
645. State errors flat: location, cause, fix.
65 
66The full ruleset is the canonical file. Read it before you write documentation.
67 
68## Verify every claim about a harness
69 
70`INSTALL.md` states what Claude Code, Codex, Cursor, Gemini CLI, Copilot, and
71Zed each do. No test can check those claims. A harness changes them without
72warning, and a wrong path costs a reader their install.
73 
74Check a claim against the vendor's current documentation or the installed CLI
75before you write it. Four claims in this file's history were wrong: a skills
76directory, a namespaced skill name, a CLI subcommand, and a library's release
77notes.
78 
79## Documentation parity
80 
81Six READMEs carry the same content: `README.md` and five translations under
82`.github/readme/`. Three things must match across all six.
83 
841. Every `bash`, `json`, and `toml` code fence, character for character.
852. Every inline code span, as a multiset. Word order is the translator's.
863. The numbered shape rules, `1..N`, matching the canonical count.
87 
88`tests/test_readmes.py` enforces all three. A change to any command in
89`README.md` is a change to six files.
90 
91## Gates
92 
93Run these four before you push. CI runs the same four.
94 
95```bash
96python3 scripts/sync_style.py --check
97```
98 
99```bash
100python3 scripts/check_configs.py
101```
102 
103```bash
104python3 scripts/run_evals.py validate
105```
106 
107```bash
108python3 -m unittest discover -s tests -v
109```
110 
111CI runs a fifth gate you cannot skip: it rebuilds the ledger and fails when the
112result differs from the committed file. Run it after any freeze.
113 
114```bash
115python3 scripts/ledger.py index
116```
117 
118Python 3.11 is the floor. CI runs the tests on 3.11 and 3.14.
119`scripts/check_configs.py` needs PyYAML.
120 
121## The hero card
122 
123`.github/assets/hero.png` is the image at the top of all six READMEs, and the
124file uploaded as the repository's social preview. Redraw it after any change to
125its header text, its example, or its harness list:
126 
127```bash
128python3 scripts/make_card.py
129```
130 
131It needs Pillow and NumPy, and it reads the five vendored fonts in
132`assets/fonts/`. Neither package is a test dependency, so no gate runs this
133script and no gate compares the committed PNG against a fresh render. Pillow
134encodes the same pixels differently across versions, so a checksum gate would
135fail on an unrelated upgrade. Commit the redrawn file yourself.
136 
137Two facts about the card that no test can hold:
138 
1391. The card cites `src/auth.ts:47`, the same edit the README's "What changes"
140   section cites. Change one and you change both.
1412. Uploading the social preview is manual. GitHub takes `og:image` from
142   Settings, General, Social preview, not from README content, and exposes no
143   REST endpoint for it. Merging a new card does not change any link preview.
144 
145## Evaluations
146 
147The harness in `scripts/run_evals.py` scores the style against an unstyled
148baseline. Three rules protect the result.
149 
1501. Iterate against the `dev` split. The `holdout` split is for the final run.
1512. Freeze a finished run with `python3 scripts/ledger.py freeze`. Never edit
152   `evals/results/LEDGER.md`; `ledger.py index` rebuilds it.
1533. Two runs compare only when the model and the four input hashes match.
154 
155Design notes: [`evals/README.md`](./evals/README.md).
156 
157### Filing a finished run
158 
159A run costs about $11 and takes about two hours. File it so the next one can
160read it.
161 
162`evals/results/` holds `LEDGER.md` and `runs/`. Nothing else. The five files
163the pipeline writes there are working state, not the committed form. Freeze
164moves them:
165 
166```bash
167python3 scripts/ledger.py freeze \
168  --run-id 002 --slug recorded-model-rerun --date 2026-08-03 \
169  --judge-cost 7.19 --note &quot;...&quot; --note &quot;...&quot;
170python3 scripts/ledger.py index
171```
172 
173Commit `runs/<id>-<slug>/` and the rebuilt `LEDGER.md` together. Never commit
174a loose `responses.jsonl`, `blind.jsonl`, `blind-key.jsonl`,
175`judgements.jsonl`, or `scores.jsonl`.
176 
177Four rules on top of that.
178 
1791. Pass one `--note` per finding. The notes reach `manifest.json`,
180   `report.md`, and `LEDGER.md`. A finding you leave in a pull request
181   comment is lost the moment the branch merges.
1822. Write the note against the run that produced it. Never edit a frozen run
183   to match what a later run found. Run 001 carries a note saying run 002
184   reworded the isolation prompt. Run 002 reworded nothing. The note stays
185   wrong, because rewriting it would rewrite finished history.
1863. Say what a run cannot compare against. `freeze` derives the comparability
187   key, but only a note explains why the key moved. Change one input per run.
1884. Report the share of the delta, not just the delta. Language and concision
189   carry 20% of the weight and restate the style's own rules. When they supply
190   most of the gain, the run measured prose control, and the correctness
191   number sits inside a confidence interval that crosses zero.
192 
193### The isolation prompt
194 
195`evals/runners.example.json` carries the runner system prompt. It must forbid
196inspecting the environment and deny no capability a case grants. Two wordings
197broke that and each cost a full run.
198 
199`tests/test_run_evals.py` guards it with a negation-plus-capability pattern,
200not a list of literal phrases. The literal list passed the second bad wording
201through. Add any new denial you find to `CONTAMINATED_WORDINGS`.
202 
203Editing this prompt changes the runner config hash, so no later run compares
204against an earlier one. Freeze the run before you touch it.
205 
206## Git
207 
208Branch, then open a pull request. Never push to `main`. Merge with a rebase, so
209the history stays linear.
210 
211A commit subject states what changed. The body states why, with the evidence:
212the eval delta, the judge's note, the vendor's documentation, or the failing
213command. See `git log` for the shape.
214 
215Pull requests from outside contributors are closed at the repository level. See
216[`CONTRIBUTING.md`](./CONTRIBUTING.md).
217 
218## Layout
219 
220| Path | What it holds |
221|---|---|
222| `output-styles/attention-control.md` | the canonical style, the source of every copy |
223| `scripts/sync_style.py` | the generator and its `--check` gate |
224| `scripts/run_evals.py`, `scripts/judge.py`, `scripts/ledger.py` | the eval harness |
225| `scripts/check_configs.py` | parses every shipped manifest, TOML, and YAML file |
226| `scripts/make_card.py` | draws `.github/assets/hero.png`, the README and social-preview image |
227| `assets/fonts/` | the five vendored fonts the card is drawn with, and both OFL licenses |
228| `evals/` | cases, rubric, frozen runs, ledger |
229| `.claude-plugin/`, `.codex-plugin/`, `gemini-extension.json` | the plugin manifests |
230| `skills/attention-control/SKILL.md` | the style as a skill, for every non-Claude harness |
231| `GEMINI.md` | the style, shipped as the Gemini extension's context file |
232| `.gemini/settings.json` | the context file list for an agent working here |
233