AGENTS.md

Keep this file short and behavioral. Architecture, product behavior, and design rationale belong in docs/architecture.md and docs/adr/README.md.

Development Principles

Minimizing concepts, duplication, and ceremony.
Prefer a single stable contract with one real owner.
Prefer local simplicity over premature or speculative abstraction.
Add indirection only when it removes real coupling or protects a real boundary.
Tests should protect real stable contracts and invariants, not drive the spec or exist only for regression prevention.

When caller and callee are both local and no real boundary exists, change both directly; do not preserve local call shapes.
If a field, method, wrapper, or abstraction has no clear, current use and does not protect a real boundary, remove it immediately.
No wrapper functions or helpers unless they remove real coupling or protect a real boundary.
Prefer direct code over layers, facades, and indirection.
Prefer flattening and merging nearby responsibilities over splitting by default.
Remove dead fields, methods, config, and stale state while touching nearby code.
Do not duplicate normalization, validation, or defaulting logic; keep it in a single real owner.
Keep shared stateless transforms in utils/; keep stateful and domain-shaped logic with the real owner.
Keep stable shared contracts, constants, and public paths in types/, not in runtime or helpers.
Resolve complexity in the lowest coherent owner and expose only the minimum surface upward.
Shared runtime logic must live in one real owner and be reused, not mirrored.