How It Works

YotoShelf uses an explicit contributor contract documented in AGENTS.md. The rules are designed to keep changes safe, reviewable, and reversible — they apply equally to human contributors and AI coding agents.

Stop conditions

Stop immediately and explain what happened (do not attempt another fix) if:

• Tests have failed twice on the same task — revert with git checkout -- .
• A change is about to touch a fourth file — the blast radius limit is three files per commit
• A test is being modified to make code pass — the tests are the specification; the code is wrong
• The purpose of a function is unclear — read it, read its tests, read its callers before proceeding
• The build has been broken for more than two attempts — revert everything and start over

Core rules

Read before write

Before modifying any file: read the entire file, read the test file for the package, run existing tests, make the change, run tests again immediately. Skipping the read step is the most common source of regressions.

Test before fix

Before fixing a bug: write a test that demonstrates the bug, confirm it fails, fix the code, confirm it passes, then run go test ./... -count=1 to confirm nothing else broke. If a failing test cannot be written, the bug is not yet understood.

Revert on regression

After every change, run go test ./... -count=1. If any previously-passing package now fails, revert first — do not patch the regression inline.

One thing at a time

Each commit addresses exactly one bug or one feature. No "while I'm here" changes. If a second issue is found while working on the first, note it and move on.

Blast radius limit

Each commit touches at most three files. Fixes requiring more than three files need human approval before proceeding.

Protected files

The following files affect the entire system and require human approval before modification:

• internal/api/helpers.go — shared API helpers
• internal/api/errors.go — named error constants
• internal/api/api.go — API struct and middleware wiring
• internal/server/server.go — server wiring
• internal/db/migrations/ — database schema migrations
• sqlc.yaml — sqlc configuration
• .gitlab-ci.yml — CI pipeline definition
• AGENTS.md — this contract

Prohibited patterns

• No raw http.Error() — use huma errors or the Err() helper
• No raw SQL in handlers — use sqlc-generated queries
• No raw fetch() in the frontend — use the shared typed client
• No any types in TypeScript — use the generated types from types.ts
• No hand-editing generated files (types.ts, db/gen/, openapi.yaml)
• No new patterns — find an existing example of the same structure and follow it exactly

The full contract is in the repository: AGENTS.md. Read it before opening a merge request.