AGENTS.md

This file gives general operating guidance for coding agents working in this repository.

Core Principles

Prefer simple, maintainable solutions over clever ones.
Preserve existing behavior unless the task explicitly requires a change.
Make the smallest reasonable change that fully solves the problem.
Keep code readable: clear names, straightforward control flow, and minimal indirection.
Treat tests, types, and linting as part of the implementation, not as optional cleanup.
Work in small, coherent increments that can be verified and committed cleanly.

Match the style and structure already used in the repository.
Avoid broad refactors unless they are necessary to complete the task.
Add comments only where intent would otherwise be unclear.
Prefer explicit, boring code over abstractions introduced too early.
Keep public APIs, file layouts, and naming stable unless the task calls for a change.

Create or update tests for every non-trivial behavior change.
Prefer tests that prove the user-visible or contract-level behavior, not just implementation details.
Run relevant tests frequently while working, not only at the end.
After each meaningful code change, run the smallest test scope that gives fast feedback.
Before finishing, run the most relevant broader verification available for the touched area.
If a change is not practical to test automatically, state that clearly and explain the gap.

Never overwrite or revert user changes unless explicitly asked.
Avoid destructive commands unless the user clearly requested them.
Call out assumptions when they materially affect behavior.
If you find unrelated problems, note them separately rather than folding them into the same change.

Commit work in logical, reviewable increments rather than as one large batch.
Prefer a commit after each completed unit of work that passes relevant verification.
Keep commits focused; avoid mixing unrelated changes.
Use clear commit messages that describe the behavior or intent of the change.
Do not commit broken work unless the user explicitly asks for a checkpoint commit.

Do new feature work on a dedicated branch rather than directly on the main line.
Use a distinct branch for each feature, fix, or clearly scoped task.
Do not mix unrelated work on the same branch.
Start new work from dev unless the user specifies otherwise.
Keep branch names descriptive and scoped to the task.
Before switching branches, check for uncommitted work and avoid carrying unrelated changes forward.
If the current branch is not appropriate for the requested task, create or switch to a better-scoped branch before editing code.
Merge completed feature branches into dev after relevant verification passes.
Reserve main for release-ready code.

Keep AI coordination files on a dedicated ai branch unless the user specifies otherwise.
Treat files such as AGENTS.md, PLAN.md, task notes, and other agent-only working documents as AI metadata rather than product code.
Do not mix AI metadata commits with application feature commits.
When updating AI metadata, switch to ai before editing or committing those files.
Keep the ai branch distinct from dev and main unless the user explicitly wants those files promoted.

Use a dedicated Git author identity for AI-created commits instead of the user's personal identity.
Set the Git author name for agent work to Codex.
Set the Git author email for agent work to codex@local.
Prefer per-commit identity flags such as git -c user.name="Codex" -c user.email="codex@local" commit ... instead of changing Git configuration.
If explicit author metadata is needed, use --author="Codex <codex@local>".
Do not change the user's global Git identity for agent work.
Do not rely on inherited global Git identity for AI-authored commits.

Treat dev as the active integration branch for ongoing work.
Merge dev into main only when preparing a release.
Bump the project version only as part of release preparation unless the user asks otherwise.
Keep version changes in a dedicated release commit or tightly grouped release branch work.
Tag releases from main when the repository adopts a release process.