From ac3fc73d5ad94bf2e356447e868ca0302df5123f Mon Sep 17 00:00:00 2001 From: Richard Levasseur Date: Sat, 17 Oct 2026 16:14:46 -0700 Subject: [PATCH] agents: require factoring non-trivial scripts into standalone files 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`. --- .agents/rules/github_actions_workflows.md | 7 ++++++- .agents/rules/python.md | 9 +++++++++ .agents/skills/review-code/SKILL.md | 5 +++-- .agents/skills/review-code/review-agents-prompt.md | 4 ++++ .agents/skills/review-code/review-python-prompt.md | 8 ++++++-- .agents/skills/review-code/review-workflows-prompt.md | 5 +++++ AGENTS.md | 5 +++++ 7 files changed, 38 insertions(+), 5 deletions(-) diff --git a/.agents/rules/github_actions_workflows.md b/.agents/rules/github_actions_workflows.md index f53c69530f..7c59824f97 100644 --- a/.agents/rules/github_actions_workflows.md +++ b/.agents/rules/github_actions_workflows.md @@ -20,7 +20,12 @@ globs: ".github/workflows/**" `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 dbc134013f..9921b5a597 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 2d1d2825be..03236e42df 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md @@ -25,8 +25,9 @@ file from `.agents/skills/review-code/`: 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 a708405b9d..d9af2f9924 100644 --- a/.agents/skills/review-code/review-agents-prompt.md +++ b/.agents/skills/review-code/review-agents-prompt.md @@ -13,5 +13,9 @@ against `AGENTS.md`: 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 711ff7aecf..0e43eafaf8 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 @@ Your sole task is to audit all Python source (`.py`) and test changes in 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 50bc446d5c..afec077e1b 100644 --- a/.agents/skills/review-code/review-workflows-prompt.md +++ b/.agents/skills/review-code/review-workflows-prompt.md @@ -20,5 +20,10 @@ conventions: 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 f5c650d4cd..dea8b47413 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,6 +32,11 @@ into the sentence, not verbatim. 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