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. 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:

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.

python3 scripts/sync_style.py --check

python3 scripts/check_configs.py

python3 scripts/run_evals.py validate

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.

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:

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.

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:

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/<id>-<slug>/ 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.

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