agents: document repo rule, internal label, and workflow rules (#4306)

Document conventions for Starlark repository rules, internal toolchain
and rendering helpers, and Linux-only workflow script tests so agents
follow consistent patterns without repeating past review feedback.

.agents/rules/github_actions_workflows.md

diff --git a/.agents/rules/github_actions_workflows.md b/.agents/rules/github_actions_workflows.md
index f4c2892..d8fabb8 100644
--- a/.agents/rules/github_actions_workflows.md
+++ b/.agents/rules/github_actions_workflows.md
@@ -53,10 +53,16 @@
   (such as multi-line shell or Python logic) into standalone files (e.g. `.sh`
   or `.py` files) instead of inlining them in workflow YAML steps (`run: |`),
   shell scripts, or command invocations via heredocs (`<< 'EOF'`) or `-c` flags
-  (`bash -c`, `python3 -c`).
+  (`bash -c`, `python3 -c`). For single-line substitutions in shell scripts, use
+  `sed --in-place`.
+* **Shell Rules**: Consult the shell rules when writing shell code in workflows
+  or action scripts.
 * **Executable Permissions**: Workflow step scripts must have `chmod +x` (mode
   `100755`) and a shebang (e.g. `#!/usr/bin/env python3`).
 * **Test Location**: Place workflow tests under `tests/workflows/`.
+* **Platform Constraints**: Set
+  `target_compatible_with = ["@platforms//os:linux"]` on tests for Linux-only
+  workflow scripts instead of adding macOS/BSD workarounds.
 * **Imports over `sys.path`**: Never alter `sys.path`. Define a `py_library`
   with `imports = ["../../.github/workflows"]` in `tests/workflows/BUILD.bazel`.
 * **Functional Design & Fixtures**: Keep scripts functional with one public

.agents/rules/rules_python.md

diff --git a/.agents/rules/rules_python.md b/.agents/rules/rules_python.md
index f38ad07..b18c178 100644
--- a/.agents/rules/rules_python.md
+++ b/.agents/rules/rules_python.md
@@ -21,3 +21,13 @@
   logic, feature guards, or comments for older Bazel versions.
 * When guarding a feature added after `MINIMUM_BAZEL_VERSION`, verify and
   comment the exact Bazel version that introduced it.
+
+## Internal Labels & Helpers
+* **Toolchain Type Labels**: Define toolchain type constants in
+  `//python/private/toolchain_types:toolchain_types.bzl` and targets in
+  `//python/private/toolchain_types:BUILD.bazel`.
+* **`render` Helpers (`//python/private:text_util.bzl`)**: Use `render.*`
+  (`render.string`, `render.toolchain`, `render.call`, `render.list`) instead of
+  `repr()` when generating Starlark calls.
+* **`@bazel_tools` `bzl_library` Deps**: Use `"//python/private:bazel_tools"` in
+  `bzl_library` `deps` for files loading `@bazel_tools//...`.

.agents/rules/starlark.md

diff --git a/.agents/rules/starlark.md b/.agents/rules/starlark.md
index 0f64a7d..a0213ad 100644
--- a/.agents/rules/starlark.md
+++ b/.agents/rules/starlark.md
@@ -61,6 +61,20 @@
   freeze). Use `tuple[T]` or `depset[T]` in providers placed into depsets; do
   not use mutable `list[T]`.
 
+## Repository Rules & Code Generation
+* **Structured Attributes**: Pass separate typed attributes (`attr.string_list`,
+  `attr.string_list_dict`) instead of pre-rendered `BUILD` text or JSON blobs;
+  render `BUILD.bazel` in the rule implementation.
+* **Single-Value Templates**: For generated file templates with one interpolated
+  value, use a top-level string and `.format()`.
+* **Reuse `http_file`**: Use `http_file` from
+  `@bazel_tools//tools/build_defs/repo:http.bzl` for single-file downloads. Omit
+  `downloaded_file_path` unless required and reference `@<repo>//file`.
+* **`rctx.read()` Files**: Do not add `exports_files()` for files only read via
+  `rctx.read(Label(...))`.
+* **`repository_ctx.repo_metadata`**: `repository_ctx.repo_metadata` was
+  introduced in Bazel 8.3.0.
+
 ## Code Style & Conventions
 * **Direct Attribute Access**: Use normal attribute access (`x.field`) instead
   of `getattr(x, "field", default)` for fields defined on a provider or struct
@@ -77,6 +91,8 @@
   above `provider()` declarations that do not end in `Info` (e.g. `*Fileset`).
 * **`config_setting` Naming**: Prefix `config_setting` names with `is_` (e.g.
   `is_linux_x86_64`), so that `select()` keys read as conditions.
+* **Explicit Required Parameters**: Declare required parameters explicitly
+  instead of passing them through `**kwargs`. Document `Args:` and `Returns:`.
 * **Docstring Formatting Invariants**: Use triple-quoted strings for multi-line
   docstrings without trailing backslashes (`\`) for line continuation.
 * **Workaround Comments**: Comment non-obvious workarounds with the intent, why