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

## Before Making Changes

- Inspect the relevant files and local patterns before editing.
- Identify the narrowest safe change surface.
- Check whether there are existing tests, scripts, or conventions to follow.
- Do not assume missing context; infer from the codebase first.

## Implementation Guidance

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

## Testing Expectations

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

## Safety Rules

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

## Verification

- Run the smallest relevant verification available after making changes.
- If tests or checks cannot be run, say so explicitly.
- When possible, verify both the happy path and the most likely failure path.

## Commit Discipline

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

## Branch Discipline

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

## AI Metadata Branch

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

## Agent Identity

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

## Release And Versioning

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

## Communication

- Be concise and concrete.
- Summarize what changed, why it changed, and how it was verified.
- Surface risks, tradeoffs, and follow-up work plainly.

## Scope

- This file is intentionally general.
- Add stack-specific or workflow-specific guidance here as the repository grows.