stupidtools/AGENTS.md

AGENTS.md

Operating rules for anyone working in this repo, human or agent. The project: a GNU AutoTools replacement in C that reads a KDL build file and emits a POSIX-sh ./configure. Yes, the name is the joke. The rules below are not.

1. C23 only

Write C23 (ISO/IEC 9899:2024). Compile with -std=c23 and -Wall -Wextra -Wpedantic. Never target C20 (it does not exist as a ratified standard), never use C2y (the next draft). The build breaks on anything else.

2. Vendoring: thirdparty/ only, license + pinned SHA

Every third-party library is vendored in-tree under thirdparty/<name>/, with all three of:

• the upstream LICENSE file (never omitted, never stubbed),
• an UPSTREAM file recording the source URL and the pinned upstream commit SHA,
• a row in the thirdparty/README.md provenance table (name, version, license, SHA).

No git submodules. If it is not vendored this way, it does not exist.

3. Tests: TDD, make check + tests/run.sh

• Unit tests use the vendored single-header C test framework and run via make check.
• Shell integration tests live in tests/*.sh and are invoked by tests/run.sh, asserting exact exit codes and grep-able output markers.
• TDD workflow: write the test alongside the code. Implementation + test is one unit of work, never separated.

4. Generated configure scripts: POSIX-sh only

The emitted ./configure must run unmodified under dash, bash, and zsh. Banned constructs, no exceptions:

• [[ ]]
• arrays
• local
• == (use = with [, or case)
• <<<
• &>

set -e IS POSIX, but it is avoided by policy in generated scripts because its failure semantics vary across shells. Do not rely on it; make the script fail explicitly. dash is the strict oracle: dash -n must pass on everything we generate.

For build, test, and commit workflows, see CONTRIBUTING.md.