Add AGENTS.md with agent/contributor guidance

[davidbyttow]

Summary

Adds an AGENTS.md so agents (and new contributors) get the repo's working knowledge up front:

• Setup and commands (build, make test, make clean-cache, go generate ./vips), and that CI is the authoritative gate.
• Package layout: generated vs hand-written C bridge, and where the Go API lives.
• The cgo/memory rules that have caused real bugs when broken, each tied to the issue that proved it: libvips input-ref ownership (Fix input double-unref in Join (intermittent SIGSEGV) #531), band-count background vectors (Error when embedding background for 2-band png #534), version guards for new libvips properties (Add TargetSize option to WebpExportParams #535), signature-based format detection over loader nicknames (Sniff stream signature to preserve sub-format detection #540).
• Testing conventions: golden-file naming and first-run behavior, the leak detector (OpenImageRefs/AssertNoLeaks), synthesized fixtures over committed binaries, byte-identity between streaming savers and Export*.
• Known macOS-local environmental failures so nobody blames them on a change under review.

CLAUDE.md now defers to AGENTS.md for the shared content and keeps only the Claude-specific worktree flow, so the two files can't drift.

🤖 Generated with Claude Code

Note

Add AGENTS.md with contributor and AI agent guidance

Moves setup instructions, common commands, repo layout, cgo/memory rules, testing conventions (golden files, leak detection, streaming parity), and macOS quirks into a new AGENTS.md file. Updates CLAUDE.md to defer to AGENTS.md rather than duplicating that content.

📊 Macroscope summarized 52e336a. 2 files reviewed, 0 issues evaluated, 0 issues filtered, 0 comments posted

🗂️ Filtered Issues

No issues evaluated.

[macroscopeapp]

🟡 Medium AGENTS.md:45

The statement that ImageRef methods are guarded with r.lock is inaccurate: only a small subset of methods (Close, SetKill, setImage, and streaming materialize/write paths) acquire that mutex, while normal transform/export/metadata methods do not. This can mislead contributors into assuming concurrent method calls (including concurrent Close) are safe, when the underlying mutable VipsImage pointer is not protected on most paths. Consider correcting the wording to state that r.lock guards lifecycle/ownership transitions only, not general method calls, and add a note that callers must not invoke methods concurrently on the same ImageRef.

Suggested change

`ImageRef` is a mutable handle: operations replace the underlying `VipsImage` via `setImage` (which unrefs the old one). `Close` and a GC finalizer release the ref; methods guard with `runtime.KeepAlive(r)` and `r.lock`.

`ImageRef` is a mutable handle: operations replace the underlying `VipsImage` via `setImage` (which unrefs the old one). `Close` and a GC finalizer release the ref. Only lifecycle/ownership transitions (`Close`, `SetKill`, `setImage`, streaming materialize/write paths) acquire `r.lock`; normal transform/export/metadata methods do not, so callers must not invoke methods concurrently on the same `ImageRef`.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @AGENTS.md around line 45:

The statement that `ImageRef` methods are guarded with `r.lock` is inaccurate: only a small subset of methods (`Close`, `SetKill`, `setImage`, and streaming materialize/write paths) acquire that mutex, while normal transform/export/metadata methods do not. This can mislead contributors into assuming concurrent method calls (including concurrent `Close`) are safe, when the underlying mutable `VipsImage` pointer is not protected on most paths. Consider correcting the wording to state that `r.lock` guards lifecycle/ownership transitions only, not general method calls, and add a note that callers must not invoke methods concurrently on the same `ImageRef`.