# Working in this repository This repository ships one output style to seven coding agents. One file is canonical. Everything else is generated from it or checked against it. Read this before you edit anything here. ## The one rule that breaks the build Edit [`output-styles/attention-control.md`](./output-styles/attention-control.md). Never edit a generated file. These files are generated. Each carries a "Do not edit this file" marker: | Generated file | Built from | |---|---| | `skills/attention-control/SKILL.md` | the canonical style | | `.cursor/skills/attention-control/SKILL.md` | the canonical style | | `.cursor/rules/attention-control.mdc` | the canonical style | | the snippet section of `INSTALL.md` | the canonical style | | `AGENTS.md` | `CLAUDE.md` | `AGENTS.md` and `CLAUDE.md` say the same thing. Edit `CLAUDE.md` and run the generator; the mirror follows. ## Which file your tool reads | Tool | Reads | For | |---|---|---| | Claude Code | `CLAUDE.md` | these standards | | Cursor | `AGENTS.md` and `CLAUDE.md`, both automatic | these standards | | Gemini CLI | `AGENTS.md`, then `GEMINI.md` | these standards, then the style | | Any other agent-instruction harness | `AGENTS.md` | these standards | `GEMINI.md` is not a repository guide. `gemini-extension.json` names it as the extension's context file, so it is what a Gemini CLI user gets when they install this style. Leave it as the style. `.gemini/settings.json` adds `AGENTS.md` to the context list, so a Gemini agent working here reads the standards and the style. It changes nothing for anyone who installs the extension. After any edit to a source file, run: ```bash python3 scripts/sync_style.py ``` CI fails when a copy drifts. `scripts/sync_style.py --check` is the gate. ## Write in the style you are editing This repository uses its own output style. Apply it to your responses and to the prose you write into these files. 1. Lead with the next action. A command, a path, or a snippet goes first. 2. Do the work you own. Never hand back a step you can finish yourself. 3. Give the runnable thing. "Run the migration script" is a label. The path or the snippet is an action. 4. Never invent a specific. A version, a date, a flag, or a line number you cannot check is a fabrication, whatever tone you write it in. 5. State errors flat: location, cause, fix. The full ruleset is the canonical file. Read it before you write documentation. ## Verify every claim about a harness `INSTALL.md` states what Claude Code, Codex, Cursor, Gemini CLI, Copilot, and Zed each do. No test can check those claims. A harness changes them without warning, and a wrong path costs a reader their install. Check a claim against the vendor's current documentation or the installed CLI before you write it. Four claims in this file's history were wrong: a skills directory, a namespaced skill name, a CLI subcommand, and a library's release notes. ## Documentation parity Six READMEs carry the same content: `README.md` and five translations under `.github/readme/`. Three things must match across all six. 1. Every `bash`, `json`, and `toml` code fence, character for character. 2. Every inline code span, as a multiset. Word order is the translator's. 3. The numbered shape rules, `1..N`, matching the canonical count. `tests/test_readmes.py` enforces all three. A change to any command in `README.md` is a change to six files. ## Gates Run these four before you push. CI runs the same four. ```bash python3 scripts/sync_style.py --check ``` ```bash python3 scripts/check_configs.py ``` ```bash python3 scripts/run_evals.py validate ``` ```bash python3 -m unittest discover -s tests -v ``` CI runs a fifth gate you cannot skip: it rebuilds the ledger and fails when the result differs from the committed file. Run it after any freeze. ```bash python3 scripts/ledger.py index ``` Python 3.11 is the floor. CI runs the tests on 3.11 and 3.14. `scripts/check_configs.py` needs PyYAML. ## The hero card `.github/assets/hero.png` is the image at the top of all six READMEs, and the file uploaded as the repository's social preview. Redraw it after any change to its header text, its example, or its harness list: ```bash python3 scripts/make_card.py ``` It needs Pillow and NumPy, and it reads the five vendored fonts in `assets/fonts/`. Neither package is a test dependency, so no gate runs this script and no gate compares the committed PNG against a fresh render. Pillow encodes the same pixels differently across versions, so a checksum gate would fail on an unrelated upgrade. Commit the redrawn file yourself. Two facts about the card that no test can hold: 1. The card cites `src/auth.ts:47`, the same edit the README's "What changes" section cites. Change one and you change both. 2. Uploading the social preview is manual. GitHub takes `og:image` from Settings, General, Social preview, not from README content, and exposes no REST endpoint for it. Merging a new card does not change any link preview. ## Evaluations The harness in `scripts/run_evals.py` scores the style against an unstyled baseline. Three rules protect the result. 1. Iterate against the `dev` split. The `holdout` split is for the final run. 2. Freeze a finished run with `python3 scripts/ledger.py freeze`. Never edit `evals/results/LEDGER.md`; `ledger.py index` rebuilds it. 3. Two runs compare only when the model and the four input hashes match. Design notes: [`evals/README.md`](./evals/README.md). ### Filing a finished run A run costs about $11 and takes about two hours. File it so the next one can read it. `evals/results/` holds `LEDGER.md` and `runs/`. Nothing else. The five files the pipeline writes there are working state, not the committed form. Freeze moves them: ```bash python3 scripts/ledger.py freeze \ --run-id 002 --slug recorded-model-rerun --date 2026-08-03 \ --judge-cost 7.19 --note "..." --note "..." python3 scripts/ledger.py index ``` Commit `runs/-/` and the rebuilt `LEDGER.md` together. Never commit a loose `responses.jsonl`, `blind.jsonl`, `blind-key.jsonl`, `judgements.jsonl`, or `scores.jsonl`. Four rules on top of that. 1. Pass one `--note` per finding. The notes reach `manifest.json`, `report.md`, and `LEDGER.md`. A finding you leave in a pull request comment is lost the moment the branch merges. 2. Write the note against the run that produced it. Never edit a frozen run to match what a later run found. Run 001 carries a note saying run 002 reworded the isolation prompt. Run 002 reworded nothing. The note stays wrong, because rewriting it would rewrite finished history. 3. Say what a run cannot compare against. `freeze` derives the comparability key, but only a note explains why the key moved. Change one input per run. 4. Report the share of the delta, not just the delta. Language and concision carry 20% of the weight and restate the style's own rules. When they supply most of the gain, the run measured prose control, and the correctness number sits inside a confidence interval that crosses zero. ### The isolation prompt `evals/runners.example.json` carries the runner system prompt. It must forbid inspecting the environment and deny no capability a case grants. Two wordings broke that and each cost a full run. `tests/test_run_evals.py` guards it with a negation-plus-capability pattern, not a list of literal phrases. The literal list passed the second bad wording through. Add any new denial you find to `CONTAMINATED_WORDINGS`. Editing this prompt changes the runner config hash, so no later run compares against an earlier one. Freeze the run before you touch it. ## Git Branch, then open a pull request. Never push to `main`. Merge with a rebase, so the history stays linear. A commit subject states what changed. The body states why, with the evidence: the eval delta, the judge's note, the vendor's documentation, or the failing command. See `git log` for the shape. Pull requests from outside contributors are closed at the repository level. See [`CONTRIBUTING.md`](./CONTRIBUTING.md). ## Layout | Path | What it holds | |---|---| | `output-styles/attention-control.md` | the canonical style, the source of every copy | | `scripts/sync_style.py` | the generator and its `--check` gate | | `scripts/run_evals.py`, `scripts/judge.py`, `scripts/ledger.py` | the eval harness | | `scripts/check_configs.py` | parses every shipped manifest, TOML, and YAML file | | `scripts/make_card.py` | draws `.github/assets/hero.png`, the README and social-preview image | | `assets/fonts/` | the five vendored fonts the card is drawn with, and both OFL licenses | | `evals/` | cases, rubric, frozen runs, ledger | | `.claude-plugin/`, `.codex-plugin/`, `gemini-extension.json` | the plugin manifests | | `skills/attention-control/SKILL.md` | the style as a skill, for every non-Claude harness | | `GEMINI.md` | the style, shipped as the Gemini extension's context file | | `.gemini/settings.json` | the context file list for an agent working here |