commit 7f4a4beb5ad8f776aa273c9f34339c01e423688a Author: Codex Date: Fri Apr 17 08:12:46 2026 -0500 Add agent workflow guidance diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..59e4ba7 --- /dev/null +++ b/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 "`. +- 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.