Skip to content

AGENTS.md

Latest commit

 

History

History
86 lines (63 loc) · 4.42 KB

AGENTS.md

File metadata and controls

86 lines (63 loc) · 4.42 KB
Raw

Contribution Guidelines for AI Coding Agents

These are the canonical contribution and commit rules for this repository. They apply to every AI coding agent used on this project (OpenAI Codex, Cursor, GitHub Copilot, Claude Code, Gemini CLI, and others) and to any automation acting on a contributor's behalf.

This file (AGENTS.md) is the single source of truth. Most agents read it natively; the few that use a dedicated file load these same rules from here — .claude/CLAUDE.md and GEMINI.md import it, and .github/copilot-instructions.md points to it — so there is only ever one copy to maintain.

Commit Authorship

Every commit in this repository must be authored by a human (the contributor). No AI agent (Codex, Cursor, GitHub Copilot, Claude, Gemini, or any other) may be set as the commit author.

At the end of every commit message, include an explicit attribution trailer indicating which AI model assisted, in this format:

Assisted-by: AGENT_NAME:MODEL_VERSION

For example: Assisted-by: claude-code:claude-opus-4-7 or Assisted-by: github-copilot:MODEL_VERSION.

This applies to all commits, including those created via automation or agent workflows.

Commit generation

No commit should be signed-off by an AI agent or OS. Only a human can sign-off their commits with their own certificate.

Branch Naming

  • Do not prefix branches with claude/, copilot/, codex/, cursor/, ai/, bot/, or any agent-derived namespace.
  • Do not append auto-generated suffixes (random IDs, timestamps, session hashes) unless genuinely required to disambiguate.
  • Branch names should be explicit and brief about what is being done or asked — e.g. add-commit-attribution, fix-win-hang, etc.
  • Prefer kebab-case.

PR description content

The Assisted-by attribution should be included in the PR description, but no link to the session itself should be included, as it is not publicly accessible.

When a PR fixes an issue or relates to / replaces another issue, the PR description should include a reference to the issue number after the main description but before the Assisted-by: attribution, e.g. Fixes: #123 or Closes: #124.

HIDAPI API usage contract

This is the contract HIDAPI expects of its callers. It governs both code review and code generation: judge the library's behaviour only against usage that respects it, and only generate example/test code that respects it. The authoritative reference is Multi‐threading Notes.

Library lifecycle

  • Call hid_init() before any other HIDAPI function. Implicit lazy initialization exists, but must not be relied upon when more than one thread may make the first call.
  • Call hid_exit() last, after every device has been closed. hid_exit() deinitializes the whole library; no HIDAPI function other than a new hid_init() may be called after it, and device handles obtained before it are invalid.
  • hid_init()/hid_exit() must never run concurrently with any other HIDAPI function.

Concurrency

  • HIDAPI v0.x.x is not thread-safe. The following must not be called concurrently from different threads: hid_init, hid_exit, hid_enumerate, hid_open, hid_open_path, hid_close, hid_error(NULL) — the global error string is one reason.
  • Functions taking a hid_device * are not individually thread-safe, but different devices may be used from different threads — i.e. a dedicated thread per device.
  • hid_close() must be serialized against initialization and enumeration calls.
  • Since v0.15.0, a dedicated read thread using only hid_read, hid_read_timeout and hid_read_error is safe alongside other operations on the same device from another thread. Do not use hid_error from such a thread; use hid_read_error.
  • macOS: hid_init() and hid_exit() must be called from the same thread, and that thread must stay alive until all devices are closed and hid_exit() has completed.

For AI agents and reviewers

A finding whose trigger requires violating this contract is application misuse, not a library defect. Examples: calling hid_exit() while other threads still use the API, using device handles after hid_exit(), unsynchronized concurrent first-time initialization. Do not report such scenarios as bugs, and do not add locking or other synchronization to "fix" them. Hardening the library against misuse is a maintainer design decision, not a review fix.