agents: require factoring non-trivial scripts into standalone files (#4279) Inlining multi-line Python or shell logic via heredocs, `-c` flags, or workflow `run:` blocks makes scripts harder to read, lint, and test in isolation. Additionally, `.agents/rules/python.md` lacked YAML frontmatter and was not loading automatically when editing Python or shell files. Require non-trivial scripts to be factored into standalone `.py` or `.sh` files across workspace rules and code review auditor prompts, and add glob trigger frontmatter to `.agents/rules/python.md`.
diff --git a/.agents/rules/github_actions_workflows.md b/.agents/rules/github_actions_workflows.md index f53c695..7c59824 100644 --- a/.agents/rules/github_actions_workflows.md +++ b/.agents/rules/github_actions_workflows.md
@@ -20,7 +20,12 @@ `export-subst` placeholders (such as `$Format:...$` in `python/features.bzl`) expand. Use `--add-file` to include generated files. -## Workflow Python Scripts & Testing +## Workflow Scripts & Testing +* **Separate Script Files (No Inline Scripts)**: Factor non-trivial scripts + (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`). * **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/`.
diff --git a/.agents/rules/python.md b/.agents/rules/python.md index dbc1340..9921b5a 100644 --- a/.agents/rules/python.md +++ b/.agents/rules/python.md
@@ -1,3 +1,9 @@ +--- +trigger: glob +description: Python coding, typing, CLI, and pytest conventions +globs: "*.py,*.sh" +--- + # Python Conventions ## pytest @@ -11,6 +17,9 @@ * Assume caller-guaranteed preconditions hold (e.g., input directories exist and contain files). Do not add silent no-op guards (`if path.is_dir():` or `if not path.is_file(): continue`) that mask broken invocations. +* Factor non-trivial scripts (such as multi-line Python or shell logic) into + standalone files (e.g. `.py` or `.sh` files) instead of inlining them via + heredocs (`<< 'EOF'`) or `-c` flags (`python3 -c`, `bash -c`). ## Interface & ABC Docstrings * In abstract base class / interface methods, always document `Args:`,
diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index 2d1d282..03236e4 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md
@@ -25,8 +25,9 @@ 2. **Python Code Sub-Agent** (`Role: "Python Code Auditor"`): - Prompt file: `.agents/skills/review-code/review-python-prompt.md` - - Focus: Audits Python source and test changes in `git diff` against - `.agents/rules/python.md` and Python and pytest conventions in `AGENTS.md`. + - Focus: Audits Python source, test, and inline script changes in `git diff` + against `.agents/rules/python.md` and Python and pytest conventions in + `AGENTS.md`. 3. **Documentation Sub-Agent** (`Role: "Documentation Auditor"`): - Prompt file:
diff --git a/.agents/skills/review-code/review-agents-prompt.md b/.agents/skills/review-code/review-agents-prompt.md index a708405..d9af2f9 100644 --- a/.agents/skills/review-code/review-agents-prompt.md +++ b/.agents/skills/review-code/review-agents-prompt.md
@@ -13,5 +13,9 @@ not modified unless explicitly instructed. 5. Check that all repo rules and macro conventions described in `AGENTS.md` are respected. +6. Verify non-trivial scripts (such as multi-line shell or Python logic) are + factored into standalone files (e.g. `.sh` or `.py` files) rather than + inlined via heredocs (`<< 'EOF'`), `-c` flags (`bash -c`, `python3 -c`), or + multi-line workflow `run:` blocks. @.agents/skills/review-code/review-report-format.md
diff --git a/.agents/skills/review-code/review-python-prompt.md b/.agents/skills/review-code/review-python-prompt.md index 711ff7a..0e43eaf 100644 --- a/.agents/skills/review-code/review-python-prompt.md +++ b/.agents/skills/review-code/review-python-prompt.md
@@ -1,6 +1,7 @@ You are a specialized Python & pytest Auditor sub-agent. -Your sole task is to audit all Python source (`.py`) and test changes in -`git diff` against the project's Python conventions: +Your sole task is to audit all Python changes (including `.py` files, tests, +and inline Python in shell scripts or workflows) in `git diff` against the +project's Python conventions: 1. Read and strictly enforce `.agents/rules/python.md`, `AGENTS.md`, and `CONTRIBUTING.md`. @@ -10,5 +11,8 @@ and pass the public fixture name using `@pytest.fixture(name="foo")`. 4. Verify that tests were executed using Bazel (`bazel test --config=fast-tests`) and passed. +5. Verify non-trivial scripts (such as multi-line Python or shell logic) are + factored into standalone files (e.g. `.py` or `.sh` files) rather than + inlined via heredocs (`<< 'EOF'`) or `-c` flags (`python3 -c`, `bash -c`). @.agents/skills/review-code/review-report-format.md
diff --git a/.agents/skills/review-code/review-workflows-prompt.md b/.agents/skills/review-code/review-workflows-prompt.md index 50bc446..afec077 100644 --- a/.agents/skills/review-code/review-workflows-prompt.md +++ b/.agents/skills/review-code/review-workflows-prompt.md
@@ -20,5 +20,10 @@ modify `sys.path`. 7. Verify console messaging: ensure scripts use GHA workflow command syntax (e.g. `::error::`, `::warning::`, `::notice::`, `::group::`). +8. Verify non-trivial scripts (such as multi-line shell or Python logic) are + factored into standalone files (e.g. `.sh` or `.py` files) rather than + inlined in workflow YAML steps (`run: |`), shell scripts, or command + invocations via heredocs (`<< 'EOF'`) or `-c` flags (`bash -c`, + `python3 -c`). @.agents/skills/review-code/review-report-format.md
diff --git a/AGENTS.md b/AGENTS.md index f5c650d..dea8b47 100644 --- a/AGENTS.md +++ b/AGENTS.md
@@ -32,6 +32,11 @@ When adding `{versionadded}` or `{versionchanged}` sections, add them add the end of the documentation text. +Factor non-trivial scripts (such as multi-line shell or Python logic) into +standalone files (e.g. `.sh` or `.py` files) instead of inlining them via +heredocs (`<< 'EOF'`), `-c` flags (`bash -c`, `python3 -c`), or multi-line +workflow `run:` blocks. + ### PR Updates Once a PR is created, create new commits and merges. Don't use rebase or amend