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

## Repo State Preflight

- Before starting work, inspect `git status --short`.
- Treat pre-existing dirty files as user-owned by default.
- Do not include pre-existing user edits in agent commits unless explicitly approved.
- If requested work overlaps with user-owned uncommitted files, pause and ask how to proceed.
- Encourage the user to commit or stash their work before continuing when appropriate.

## Implementation Guidance

- Match the style and structure already used in the repository.
- Avoid broad refactors unless necessary to complete the task.
- Add comments only where intent would otherwise be unclear.
- Prefer explicit, simple code over premature abstraction.
- 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 user-visible or contract-level behavior.
- Run relevant tests frequently while working.
- After each meaningful change, run the smallest test scope that gives fast feedback.
- Before finishing, run broader verification for the touched area.
- If a change cannot be tested automatically, state that clearly.

## Safety Rules

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

## Verification

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

## Documentation

- Re-read `AGENTS.md`, `PLAN.md`, and relevant files in `docs/` before planning or implementing.
- Update `docs/` when behavior, structure, or standards change.
- Update `PLAN.md` when work is completed, deferred, or split into follow-up work.
- Do not consider work complete until code and docs are aligned.

## Commit Discipline

- Commit work in logical, reviewable increments.
- Prefer a commit after each completed unit of work that passes verification.
- Keep commits focused; avoid mixing unrelated changes.
- Use clear commit messages describing behavior or intent.
- Do not commit broken work unless explicitly requested.

## Branch Discipline

- Do new feature work on a dedicated branch.
- Use a distinct branch per feature, fix, or scoped task.
- Start new work from `dev` unless specified otherwise.
- Keep branch names descriptive and scoped.
- Do not carry unrelated uncommitted changes across branches.
- Merge completed feature branches into `dev` after verification.
- Reserve `main` for release-ready code.

## AI Metadata

- Keep purely agent-only working notes on the `ai` branch unless specified otherwise.
- Do not mix AI metadata commits with application feature commits.
- If a file is required for active repo guidance, keep it in the working branch.

## Agent Identity

- Use a dedicated Git author identity for AI-created commits.
- Default agent identity:
  - Name: `Codex`
  - Email: `codex@local`
- Prefer per-commit identity flags:
  - `git -c user.name="Codex" -c user.email="codex@local" commit ...`
- Do not change the user's global Git identity.

## Commit Ownership

- The user and agents use separate Git identities.
- Only agent-authored changes should be included in agent commits.
- Do not include pre-existing user edits in agent commits unless explicitly approved.
- If overlap exists, pause and ask before proceeding.

## Release And Versioning

- Treat `dev` as the active integration branch.
- Merge `dev` into `main` only for releases.
- Bump versions only during release preparation unless instructed otherwise.
- Keep version changes grouped into release commits.
- Tag releases from `main` when applicable.

## Communication

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

## Scope

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