From 84fe6f38dcac75f95840a73aa77494f8bc317033 Mon Sep 17 00:00:00 2001
From: Richard Levasseur <richardlev@gmail.com>
Date: Sun, 16 Aug 2026 23:06:22 +0000
Subject: [PATCH] agents: refine commit type definitions and interface
 docstring rules

Clarify commit type prefixes for developer/release tooling (build:),
CI configurations (ci: for .bazelci), and GitHub Actions workflows (workflow:).
Also require interface and abstract base class docstrings to document
Args, Returns, and custom exceptions under Raises.
---
 .agents/rules/pr.md     | 8 ++++++--
 .agents/rules/python.md | 4 ++++
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/.agents/rules/pr.md b/.agents/rules/pr.md
index 092e2adbf4..9e5fa9df88 100644
--- a/.agents/rules/pr.md
+++ b/.agents/rules/pr.md
@@ -16,8 +16,12 @@ Before drafting any pull request description, strictly adhere to the rules in
 
 ## Commit & PR Types
 * `fix:` / `feat:`: User-visible changes ONLY.
-* `workflow:` / `workflows:`: Internal workflow automation, release tooling, and
-  CI scripts (e.g., `workflow(release): ...`).
+* `build:` / `build(release):`: Internal release tooling, developer workflows,
+  and build scripts (prefer `build(release):` over `chore:` or `tools:`, since
+  `tools:` could be ambiguous with production tools).
+* `ci:`: `.bazelci` and Buildkite CI configurations.
+* `workflow:` / `workflows:`: GitHub Actions workflow configurations
+  (`.github/workflows/`).
 * `tests:`: Test-only changes and test-helper fixes (never `fix:` or
   `fix(tests):`).
 
diff --git a/.agents/rules/python.md b/.agents/rules/python.md
index acef8b68c5..8091efcd00 100644
--- a/.agents/rules/python.md
+++ b/.agents/rules/python.md
@@ -9,6 +9,10 @@
 * Use direct attribute access (e.g. `args.foo`) on `argparse.Namespace` with
   well-defined shapes. Avoid defensive `getattr()`.
 
+## Interface & ABC Docstrings
+* In abstract base class / interface methods, always document `Args:`,
+  `Returns:`, and all custom exceptions raised under `Raises:`.
+
 ## Exception Handling
 * Inherit custom exceptions from `Exception`, not `RuntimeError`.