Add agent workflow guidance

AGENTS.md

@@ -0,0 +1,106 @@
+# 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.