agents: document test construct comments and rule domain separation (#4255) Document inline comment expectations for non-obvious test constructs and clarify rule trigger selection and domain separation. Unusual test constructs (such as single-branch `select()` expressions used to exercise macro `select()` handling) appear accidental without an explanatory comment. Similarly, general domain rule files (`starlark.md`, `bzl.md`, `python.md`, `docs.md`) should remain separate from `rules_python`-specific invariants (`rules_python.md`). Update `testing.md` to require inline comments on non-obvious test constructs, and update `rule-creator/SKILL.md` to document `model_decision` vs `glob` triggers and rule domain separation.
diff --git a/.agents/rules/testing.md b/.agents/rules/testing.md index cd56f69..21a0191 100644 --- a/.agents/rules/testing.md +++ b/.agents/rules/testing.md
@@ -41,3 +41,6 @@ Bzlmod with `target_compatible_with = SUPPORTS_BZLMOD` (`//tests/support:support.bzl`). WORKSPACE mode resolves pip dependencies for only the host Python version. +* **Non-Obvious Test Constructs**: Add an inline comment when a test target + uses an intentionally unusual construct (e.g., a `select()` with only + `//conditions:default` to verify macro `select()` handling).
diff --git a/.agents/skills/rule-creator/SKILL.md b/.agents/skills/rule-creator/SKILL.md index 34306e7..4a6201f 100644 --- a/.agents/skills/rule-creator/SKILL.md +++ b/.agents/skills/rule-creator/SKILL.md
@@ -32,8 +32,17 @@ #### Trigger Conditions * `always_on`: The rule is always active and must be followed for all tasks. -* Custom triggers: You can specify other trigger conditions if the rule only - applies in certain contexts. +* `model_decision`: The agent loads the rule based on its `description` when + relevant. Prefer `model_decision` for conceptual, architectural, or + cross-cutting rules (e.g., `pr.md`, `rules_python.md`). +* `glob`: The rule activates when matching files (`globs:`) are accessed. + Use for syntax/formatting rules tied to specific file types. + +### Domain Separation +* Keep language and tool rule files (`starlark.md`, `bzl.md`, `python.md`, + `docs.md`) general to those domains. +* Place `rules_python`-specific Bzlmod, PyPI, and rule API invariants in + `.agents/rules/rules_python.md`. ### Formatting Guidelines * **Line Wrapping:** Wrap all text to 80 columns.