From 11c04923f824d9b9355852f3b8bc549f51944c64 Mon Sep 17 00:00:00 2001
From: Andrew Kesterson <andrew@aklabs.net>
Date: Wed, 29 Jul 2026 17:29:49 -0400
Subject: [PATCH] Add AGENTS.md

---
 AGENTS.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..4146af5
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,64 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+`libakstdlib` is a C shared library that wraps libc calls and small data
+structures in `libakerror` error contexts. Public API declarations live in
+`include/akstdlib.h`; implementation lives in `src/stdlib.c`. Tests are
+one-file CTest executables under `tests/test_<name>.c`, with shared test helpers
+in `tests/aksl_capture.h`. CMake package templates are in `cmake/` and
+`akstdlib.pc.in`. The vendored dependency is `deps/libakerror`; update it as a
+submodule rather than editing generated files under `build/` or `build-asan/`.
+
+## Build, Test, and Development Commands
+
+Initialize dependencies before a fresh build:
+
+```sh
+git submodule update --init --recursive
+cmake -S . -B build
+cmake --build build
+```
+
+Run the normal suite with `ctest --test-dir build --output-on-failure`. Use the
+instrumented build for memory and undefined-behavior checks:
+
+```sh
+cmake -S . -B build-asan -DAKSL_SANITIZE=ON
+cmake --build build-asan
+ctest --test-dir build-asan --output-on-failure
+```
+
+Run `cmake --build build --target mutation` only when you need the slower
+mutation harness. `rebuild.sh` installs to `/home/andrew/local` and removes the
+local build directory, so treat it as a local convenience script.
+
+## Coding Style & Naming Conventions
+
+Use C with 4-space indentation; existing files sometimes use tabs for continued
+statements, so match the surrounding block. Public symbols use the `aksl_`
+prefix, structs use `aksl_<Name>`, and tests use `test_<feature>.c` plus static
+`test_<case>` functions. Preserve the `akerr_ErrorContext AKERR_NOIGNORE *`
+return convention and the `PREPARE_ERROR` / `FAIL_*` / `SUCCEED_RETURN` pattern.
+
+## Testing Guidelines
+
+Add a new test by creating `tests/test_mything.c` and adding `mything` to the
+right list in `CMakeLists.txt`. `AKSL_TESTS` must exit zero.
+`AKSL_WILL_FAIL_TESTS` are deliberate abort/contract tests.
+`AKSL_KNOWN_FAILING_TESTS` assert documented defects from `TODO.md`; when one
+starts unexpectedly passing, move it into `AKSL_TESTS` with the fix.
+
+## Commit & Pull Request Guidelines
+
+Recent commits use short imperative summaries, for example `Add memory wrapper
+tests` and `Make error-status assertions authoritative`. Keep commits focused
+and include tests with behavior changes. Pull requests should describe the
+changed API or behavior, list the CTest/sanitizer/mutation commands run, and
+link the relevant `TODO.md` item or issue when fixing a known defect.
+
+## Agent-Specific Instructions
+
+Do not modify generated build trees, profiling artifacts, or untracked scratch
+files unless explicitly asked. Prefer small, test-backed changes and update
+`README.md` or `TODO.md` when changing documented workflows or known failures.