AGENTS.md

Instructions for AI coding agents (and humans using one) proposing pull requests to this repository. This complements README.md and Maintainers.md; when in doubt, those human-facing docs win.

Repo shape (quick map)

bootrom/, armsrc/ — ARM firmware for the device (Proxmark3 hardware targets), buildable via either the top-level Makefile or their respective CMakeLists.txt. Keep both build definitions in sync.
client/ — host-side client, buildable via either the top-level Makefile or client/CMakeLists.txt. Keep both build definitions in sync.
client/experimental_lib/ — experimental shared-lib build of the client, has its own CMakeLists.txt. Any change to the client client/CMakeLists.txt almost always implies a change in client/experimental_lib/CMakeLists.txt.
common_arm/, common/ — shared code between firmware and/or client.
tools/ — standalone tool suites (hitag2crack, mfc/*, fpga_compress, ePassport, etc.), each with its own Makefile and its own check target.

Before opening a PR: build matrix

Do not treat "it compiles for me" as done. For any non-trivial change, verify across the axes below (skip only the ones genuinely unaffected by your diff, and say explicitly in the PR description which axes you did and did not test):

Zero warnings. make clean && make all must complete with no compiler warnings on the default toolchain (gcc). Warnings are effectively treated as errors in this project's normal dev flow.
Second compiler. Also try building host client and host tools (if touched) with clang, e.g. make clean && make client -j CC=clang CXX=clang++ LD=clang++ and fix anything it flags that gcc didn't — clang's diagnostics catch different classes of bugs (e.g. some format-string and sign issues).
Both client build systems. If you touched client code, dependencies, or build flags, update and test:
- client/Makefile (default make client)
- client/CMakeLists.txt
- client/experimental_lib/CMakeLists.txt A file added to one and not the others is an incomplete PR.
ARM firmware targets. If you touched armsrc/, bootrom/, common_arm/, or anything reachable from firmware, compile at least for both main platform configs (PLATFORM= per Makefile.platform): PM3RDV4 and PM5. Use also PLATFORM_EXTRAS if relevant to your changes.
Cross-OS for platform-sensitive code. Anything touching serial/USB comms, filesystem paths, threading, or conditional #ifdef _WIN32 / __APPLE__ / __linux__ code needs to at least be reasoned through, and ideally exercised, on all three supported environments: native Linux, Windows (ProxSpace or WSL, per the project's documented Windows build path), and macOS. Say in the PR which of these you actually ran.
Offline tests. Run make check (or the narrower <target>/check, e.g. client/check, armsrc/check) and make sure it stays green. Add to tools/pm3_tests.sh coverage if you're adding a new command/module that can be exercised offline.

Code style

Respect the style used in this project: trailing whitespace/EOL cleanup, Equivalent of astyle on *.c/*.h with --style=google --indent=spaces=4 --indent-switches --keep-one-line-blocks --max-continuation-indent=60 --pad-oper --unpad-paren --pad-header --align-pointer=name and on *.cpp/*.hpp (same, minus --pad-oper). Don't hand-format C/C++ differently from what astyle produces.
Don't reformat existing code outside of your changes, only format your own code.
If your change adds/changes a client command, run make commands to regenerate doc/commands.md and doc/commands.json — don't hand-edit those generated files.
Keep comments short and direct. This codebase comments in brief fragments, usually one line. Match the surrounding file. No walls of text. A comment earns its place by saying something the code cannot e.g. a return contract, where a magic number came from, or why something is deliberately absent. Do not restate the code or place commit message content, reasoning, or justification into the source. Anything longer than 3-4 lines usually belongs in the PR instead.
Preserve existing comments in code you touch or move. Don't drop, "clean up", or silently reword neighboring comments as a side effect of an unrelated change.
Keep the GPLv3 file header banner (see any existing .c/.h/Makefile) on new files; copy it verbatim from a neighboring file of the same type.

PR description format

Structure the PR description in these sections:

Problem — what's actually wrong today, with concrete symptoms/examples, not just "code is messy."
Change — what you did, file by file if it helps a reviewer, and why this approach (e.g. why runtime computation instead of a regenerated table).
Behaviour change — call out explicitly, as its own section, anything a user or downstream code could observe differently after your change, even if the new behavior is strictly more correct. Don't let this hide inside the diff.
Testing — be specific and be honest:
- List the exact build variants exercised, e.g. "readline (make), linenoise (SKIPREADLINE=1), CMake client, experimental_lib (LIBPM3), PLATFORM=PM5 and default RDV4."
- Explicitly state what you did not test (e.g. "Not tested here: Windows/ProxSpace and macOS") rather than implying full coverage. Where possible, give a one-line reason the untested paths are low-risk (e.g. "only uses scandir/alphasort, already used portably elsewhere in fileutils.c").
- Net diff size and notable deletions are worth mentioning — removing a stale generated table or dead code is a feature of the PR, not a side note.

PR checklist (put this in the PR description)

Proper style of own code, no unrelated reformatting included
Builds warning-free with gcc; also tried with clang
client/Makefile, client/CMakeLists.txt, and client/experimental_lib/CMakeLists.txt all updated if client sources changed
ARM firmware builds clean for RDV4 and PM5 platform configs (if armsrc/bootrom/common_arm touched)
Platform-sensitive code reasoned about / tested on Linux, Windows (ProxSpace/WSL), and macOS (if applicable) — state which were tested
Existing comments in touched files preserved
New comments short and direct, no restated code or PR prose
doc/commands.md / doc/commands.json regenerated if commands changed

Commit attribution

If an AI agent authored or materially contributed to a commit, say so with a trailer, the same way you'd credit a human co-author, e.g.:

Co-Authored-By: <agent/model name> <noreply@anthropic.com>

Don't omit this to make a PR look purely human-written.

What not to do

Don't add -Werror-suppressing flags or #pragma warning silences to make a warning disappear — fix the underlying issue.
Don't introduce a dependency in one client build file without mirroring it in the other two.
Don't submit ARM-side changes only test-built for one platform target.

7.1 KiB Raw Blame History