vsag: Instructions file for Codex

AGENTS.md

Read me first. This file is the entry point for AI coding agents working on VSAG. It is intentionally short. The bullets under Hard Constraints must hold for every change; the Documentation Index points at the detailed rules for each topic.

Project Overview

VSAG is a high-performance vector indexing library for similarity search, written primarily in C++ with Python bindings provided by pyvsag and Node.js/TypeScript bindings provided by vsag.

Hard Constraints (must hold every change)

• Tool versions are fixed: clang-format and clang-tidy must be version 20 exactly. Newer versions are not acceptable; CI enforces this.
• Formatting: C++ source and header files use 4-space indentation and a 100-character line limit; Markdown and other non-C++ text files have no line width limit. Use the .cpp (not .cc) suffix, and ensure every committed text file ends with a trailing newline.
• Layout: public APIs live in include/vsag/; implementation lives in src/; keep code in the vsag namespace unless the file clearly requires otherwise.
• Prefer uint64_t over size_t in code changes to avoid macOS compile issues.
• Do not modify extern/ unless the task explicitly requires third-party dependency changes.
• Tests: new features need tests; bug fixes need regression coverage; the C++ library (src/ + include/) must maintain ≥ 90 % unit-test coverage.
• Before submitting a PR: run the applicable checks removed from PR CI locally (or in an authorized remote development environment), record results, and follow the pre-submission validation requirements.
• Commits: use Conventional Commits (feat:, fix:, docs:, chore:, …) and DCO sign-off. AI agents must NOT add their own Signed-off-by: — only humans can certify the DCO. AI agents must also NOT invoke git commit -s, because -s appends Signed-off-by: at the end of the message (with a blank line separating it from earlier trailers) and breaks the required ordering. Instead, write both trailers directly in the commit message body: derive the human identity from git config user.name / user.email, place Signed-off-by: first, and follow it immediately (no blank line) with Assisted-by: <AgentName>:<ModelVersion> (e.g. Assisted-by: OpenCode:claude-opus-4.7). For [skip ci], place it at the start of the subject line.
• PR pushes: when preparing a pull request, prefer pushing the working branch to the contributor's fork rather than directly to the main antgroup/vsag repository. Push to the main repository only when explicitly required or authorized.
• Pull requests need two labels: one kind/* (kind/bug, kind/feature, kind/improvement, kind/documentation) and one version/* (e.g. version/1.0). Mergify enforces both.
• kind/bug / kind/feature PRs must link an issue in the description using a GitHub auto-closing keyword (Fixes: #N, Closes: #N, Resolves: #N; cross-repo or full issue URL also OK). kind/improvement and kind/documentation PRs are exempt. Enforced by the PR Issue Link Check Action and a Mergify protection.
• Issues do NOT carry Signed-off-by: — DCO only applies to commits.