CLAUDE.md

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