# AGENTS.md

Guidance for coding agents (Claude Code, Codex, pi, …) working in this repo.
**Read this before opening a PR.**

## MANDATORY: bump the version on every PR

Every PR that changes shippable code **must** bump the version. No exceptions —
a PR with no version bump is incomplete. Use semver:

- **patch** (`0.17.0 → 0.17.1`) — bug fixes, internal refactors, docs-only-but-shipped.
- **minor** (`0.17.0 → 0.18.0`) — new commands, flags, or user-visible behavior.
- **major** (`0.17.0 → 1.0.0`) — breaking changes to CLI, config, or data layout.

### The version lives in THREE places — keep them in sync

| File         | Where                                  | How                                   |
| ------------ | -------------------------------------- | ------------------------------------- |
| `Cargo.toml` | `version = "X.Y.Z"` (line ~3)          | **source of truth** — edit by hand    |
| `flake.nix`  | `version = "X.Y.Z";` (in `buildRustPackage`) | edit by hand to match `Cargo.toml`    |
| `Cargo.lock` | `[[package]] name = "looop"` → `version` | **auto** — regenerated by cargo       |

### Bump procedure

1. Edit `Cargo.toml` `version`.
2. Edit `flake.nix` `version` to the **exact same** string.
3. Run a build so `Cargo.lock` picks up the new version:
   ```sh
   cargo build        # or cargo check — updates Cargo.lock's looop entry
   ```
4. Verify all three agree:
   ```sh
   grep '^version' Cargo.toml
   grep 'version = ' flake.nix | head -1
   grep -A1 'name = "looop"' Cargo.lock | grep version
   ```
   All three must print the same `X.Y.Z`.
5. Stage `Cargo.toml`, `flake.nix`, **and** `Cargo.lock` together in the PR.

A mismatch between `Cargo.toml` and `flake.nix` ships a binary whose `looop
version` disagrees with the Nix package — treat it as a build break.

## Before opening a PR (checklist)

- [ ] `cargo build` is clean.
- [ ] `cargo clippy --all-targets` is clean (no new warnings).
- [ ] `cargo test` passes.
- [ ] Version bumped in `Cargo.toml` + `flake.nix`, `Cargo.lock` regenerated, all three in sync.
- [ ] `looop help` / `README.md` updated if you added or changed a command/flag.
