docs: update release notes and add AGENTS.md for project guidelines

.github/workflows/release-drafter.yml

@@ -23,12 +23,9 @@ jobs:
         run: |
           echo "## 💡 Default Clang Tool Versions" > release_notes.md
           echo "" >> release_notes.md
-          echo "Versions are resolved **dynamically from PyPI** at hook runtime. " >> release_notes.md
-          echo "The latest stable versions are always used by default — " >> release_notes.md
-          echo "no manual updates required." >> release_notes.md
-          echo "" >> release_notes.md
-          echo "You can pin a specific version by adding the \`--version\` argument " >> release_notes.md
-          echo "under \`args\` in your pre-commit config. " >> release_notes.md
+          echo "Versions are resolved dynamically from PyPI at hook runtime. " >> release_notes.md
+          echo "The latest stable versions are always used by default — no manual updates required." >> release_notes.md
+          echo "You can pin a specific version by adding the \`--version\` argument under \`args\` in your pre-commit config." >> release_notes.md
           echo "See [Custom Clang Tool Version](https://github.com/cpp-linter/cpp-linter-hooks?tab=readme-ov-file#custom-clang-tool-version) for details." >> release_notes.md
           echo "" >> release_notes.md
           cat release_notes.md

AGENTS.md

@@ -0,0 +1,53 @@
+# AGENTS.md
+
+> **IMPORTANT**: When you modify any code in this project, also update this file if the change affects agent behavior, project structure, dependencies, git workflow, or any guidance documented here.
+
+## Git Rules (MUST FOLLOW)
+
+- **Never** commit directly to `main` branch.
+- **Never** run `git push --force` on `main` branch.
+- All code changes **must** go through a Pull Request (create a feature branch, push, open PR).
+- Use conventional branch names: `feature/`, `bugfix/`, `hotfix/`, `chore/`, `release/`.
+
+## Project in a Nutshell
+
+A pre-commit hook repo that auto-installs and runs `clang-format` and `clang-tidy` from Python wheels. Supports Python 3.10+ (tested 3.9–3.14) on Windows, Linux, macOS.
+
+**Entry points** (defined in `pyproject.toml`):
+- `clang-format-hook` → `cpp_linter_hooks/clang_format.py:main`
+- `clang-tidy-hook` → `cpp_linter_hooks/clang_tidy.py:main`
+
+**Hook definitions**: `.pre-commit-hooks.yaml`
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `pyproject.toml` | Build config, deps (`pip>=26.1`, `tomli`), dev deps, entry points |
+| `cpp_linter_hooks/util.py` | PyPI version resolution + pip install (prefix matching, offline fallback) |
+| `cpp_linter_hooks/clang_format.py` | clang-format wrapper (`--verbose`, `--dry-run`) |
+| `cpp_linter_hooks/clang_tidy.py` | clang-tidy wrapper (`--compile-commands`, `--jobs`, `--fix`, error hints) |
+| `.pre-commit-hooks.yaml` | Hook metadata for pre-commit framework |
+| `testing/` | Test fixtures (`main.c`, `good.c`, `.clang-format`, `.clang-tidy`, CMakeLists) |
+| `examples/` | Example configs (CMake, large-project scoping) |
+
+## Development
+
+```bash
+uv sync --dev          # Install dev deps
+uv run pytest -vv      # Run tests
+uv run coverage run --source=tests,cpp_linter_hooks -m pytest -vv  # With coverage
+bash testing/run.sh    # Integration tests (full pre-commit pipeline)
+```
+
+## Core Patterns
+
+- **Version resolution**: Dynamic from PyPI at runtime. No hardcoded version lists. Prefix match supported (`--version=20` → `20.1.8`).
+- **Return values**: All hooks return `Tuple[int, str]` — `(0, "")` success, `(1, output)` failure, `(-1, output)` dry-run.
+- **clang-tidy compile DB**: Auto-detected from `build/`, `out/`, `cmake-build-debug/`, `_build/`. Override with `--compile-commands=<dir>`, disable with `--no-compile-commands`.
+- **clang-tidy parallel**: `--jobs=N` runs per-file in parallel. Forced serial when `--export-fixes`, `-fix`, or `-fix-errors` is used.
+
+## CI
+
+- `test.yml` — matrix (3 OS × 6 Python versions), pytest + coverage + integration tests
+- `codspeed.yml` — benchmarks via CodSpeed on path-filtered changes