prek AGENTS.md

Code Quality

• Write elegant, efficient, and concise code. Prefer simple, clear designs; concise does not mean clever.
• Prefer the smallest coherent change. Reuse existing mechanisms and avoid wrappers or abstractions for speculative or unmeasured gains.
• Prefer direct if or match control flow and explicit state types over clever combinators, wrappers, or invalid boolean/Option combinations. Prefer plain if/else to .then() or .then_some().
• Try hard to avoid panic!, unreachable!, .unwrap(), and .expect(). Encode those constraints in the type system instead. More explicit code or a larger refactor is acceptable when it avoids these calls.
• Do not narrate code in comments. Explain invariants and unusual decisions in plain language that makes sense to a first-time reader. Be more verbose when clarity requires it.
• Fix Clippy findings. If suppression is necessary, prefer a narrow #[expect(...)] with a reason.

Writing Style

• Write natural, direct English that sounds like a human collaborator, not a template or an AI-generated response.
• Avoid canned introductions, generic filler, repetition, and unnecessary summaries.
• Avoid dash-heavy prose, especially em dashes or - used to join thoughts. Prefer a period, comma, colon, or an explicit conjunction. For example, prefer This is safe because the fallback still validates the state. over This is safe - the fallback still validates the state.

Build and Tests

• Linked worktrees must share the primary Cargo target. Before running cargo or a Cargo-backed mise task, set:

  export CARGO_TARGET_DIR="$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")/target"
  

• Check existing coverage and nearby style before adding a test. Prefer focused tests; do not run the full integration suite by default.

• In integration tests, prefer cmd_snapshot! snapshot coverage over string assertions such as contains.

• Regenerate insta snapshots with the relevant test and review them with cargo insta review; do not edit them manually.