repo-lens/AGENTS.md

# Working on repo-lens

- Keep engineering simple: prefer deterministic local queries, bounded output, composable commands, and explicit context limits. Orchestrate proven tools before reimplementing them; semantic tooling must remain optional.
- Avoid speculative infrastructure, dependencies, and abstractions. Introduce complexity only for a demonstrated need; source and Git are canonical.
- Write clear, maintainable native C++. Follow surrounding code and existing formatting/tool configuration. Do not invent detailed conventions; document project conventions as they actually emerge.
- Use trailing return types where applicable. Declare `execute` overrides `[[nodiscard]]` and `noexcept`, matching the interface. Keep `noexcept` contracts honest: recoverable execution failures must be returned as exit codes rather than escaping exceptions.
- Start with `docs/PROJECTMAP.md`. Prefer available symbol lookup for known symbols, textual search for known text, and sparse semantic bookmarks for architectural concepts without suitable symbols. Search, narrow, inspect a bounded range or containing symbol, then expand only as needed. Justify whole-file reads.
- Keep context small: summarize large result sets, report limits and omitted results, and inspect callers, references, tests, or related code only when relevant. Never claim semantic classifications that the underlying evidence cannot establish reliably.
- Inspect the working tree before editing; preserve existing human changes. Keep changes focused and avoid unrelated cleanup.
- Create feature branches when requested. Never commit, merge, push, submit, or otherwise publish changes unless explicitly instructed. The human developer decides when work is complete and integrates it.
- Validate proportionately: use relevant builds/tests for implementation changes and check documentation for accuracy and scope. Report what was checked and any limitations; do not claim unrun checks passed.
- Use the matching configure/build/test preset for your host compiler; use its sanitizer preset when runtime validation is relevant. The sample test does not validate navigation behavior. Generated build trees and compilation databases are outputs, not source to edit.
- Keep `@ai-bookmark` markers sparse and unique, for stable architectural boundaries or invariants without a useful symbol. Record their routes in the project map and return bounded excerpts when using them; do not label every function or TODO.
- Keep documentation concise and useful. Update the project map when routing materially changes. Record decisions only when they preserve rationale or invariants not cheaply inferable from source and Git; do not maintain AI changelogs or persistent agent history.