pixa/AGENTS.md

Repository Rules

Last Updated 2026-10-27

These rules MUST be followed at all times. This is very important.

• Never use git add -A. Stage specific changes for a deliberate commit. A commit holds one change. After each change, make a commit with a good one-line summary.

• NEVER modify the linter config without asking first.

• NEVER modify a test to exclude special cases or otherwise make it pass without asking first. In almost all cases, change the code, NOT the test. You need explicit user approval to modify an existing test. If you think a test needs to change, make your case and ask for permission to proceed. Then stop. A bug fix may change an existing test without asking only when that test pins exactly the behavior the filed bug calls wrong. The change must then move the test to the fixed behavior and nothing else. Any other change to an existing test needs explicit user approval. Writing NEW tests needs no approval.

• When linting, assume the linter config is CORRECT. Treat each item the linter reports as something that legitimately needs fixing in the code.

• When running tests, use make test.

• Before committing, run make check. It runs make test, make lint and make fmt-check. Any issue it finds MUST be resolved before committing, unless you are explicitly told otherwise.

• When fixing a bug, write a failing test for the bug FIRST. Add appropriate logging to the test, to make sure the test is written correctly. Commit that. Then fix the bug until the test passes, without modifying the test further. Then commit the fix.

• When adding a new feature, do the same: write a test first (test-driven development, TDD). The test does not need to be very complex. Commit the test, then commit the feature.

• When adding a new feature, use a feature branch. A feature branch lands on next through a reviewed PR. The branch is merged, and then deleted, only when the feature is completely finished and the code passes make check. Only the owner merges next into main.

• Write godoc comments for all exported types and functions as you go along.

• ALWAYS be consistent in naming. If you name something one way in one place, use the EXACT SAME name in every other place.

• Be descriptive and specific in naming. wl is bad; SourceHostAllowlist is good. ConnsPerHost is bad; MaxConnectionsPerHost is good.

• This is not prototype or teaching code. It is designed for production. Any security issue (such as denial of service) or other web vulnerability is a P1 bug, the highest priority. It must be added at the top of TODO.md.

• Do not stub an implementation unless you are specifically instructed to. This is production code, and we need working implementations.

• NEVER silently fall back to a different setting when a user's parameter explicitly specifies a value. Return an error instead. For example, if a user requests format=webp and WebP encoding is not supported, return an error. Do NOT silently output PNG instead. If a user specifies fit=invalid and that fit mode does not exist, return an error. Do NOT silently default to cover. A silent fallback violates the principle of least surprise and masks bugs. Defaults are acceptable only for OMITTED parameters, never for INVALID explicit values.

• Avoid vendoring dependencies unless specifically instructed to. NEVER commit the vendor/ directory. NEVER commit compiled binaries. If such a directory or file exists and .gitignore does not list it, add it to .gitignore. Commit that .gitignore change. Keep the entire git repository, history included, under 20 MiB. Commit a larger file only when you specifically must. Media files used as test fixtures are one such case. Only OUR source code and its immediately supporting files, such as test examples, go into the repository and its history.