diff --git a/.agents/skills/create-pr/SKILL.md b/.agents/skills/create-pr/SKILL.md index 97abf1d467..1c73c66424 100644 --- a/.agents/skills/create-pr/SKILL.md +++ b/.agents/skills/create-pr/SKILL.md @@ -9,8 +9,10 @@ to a subagent. NEVER create or draft PRs directly in the main conversation. ### Instructions -1. **Pre-Review Audit**: Launch a subagent with `pre-review-audit` to verify - `git diff` conforms to all rules (line wrapping, copyright, conventions). +1. **Code Review Audit**: Launch a subagent with `review-code` to verify + `git diff` conforms to all rules (news entry in `news/`, line wrapping, + copyright, conventions, Starlark formatting). Fix any issues before + proceeding. 2. **Launch Subagent**: Use `invoke_subagent` (`TypeName: "self"`). 3. **Subagent Prompt Instructions**: - Follow `CONTRIBUTING.md` and `@/.agents/rules/pr.md`. @@ -32,8 +34,10 @@ to a subagent. NEVER create or draft PRs directly in the main conversation. `gh pr create` when explicitly requested to create the PR. - **Targeting Upstream Repo**: When creating, target upstream using `--repo bazel-contrib/rules_python` and `--head :`. -4. **Return Status**: Direct subagent to report PR number/draft status to caller. +4. **Return Status**: Direct subagent to report PR number/draft status to + caller. 5. **Link Artifact Before Asking**: Upon subagent completion, output a clickable markdown link to `pr_info.md` before prompting for confirmation. 6. **Interactive Actions**: When presenting choices via `ask_question`, always - include the clickable markdown link to `pr_info.md` in the `question` prompt. + include the clickable markdown link to `pr_info.md` in the `question` + prompt. diff --git a/.agents/skills/pre-review-audit/SKILL.md b/.agents/skills/pre-review-audit/SKILL.md deleted file mode 100644 index 1c0b16e273..0000000000 --- a/.agents/skills/pre-review-audit/SKILL.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -name: pre-review-audit -description: High-level pre-review audit of local changes when preparing to send a PR for review -trigger: model_decision ---- - -When preparing to send a Pull Request for review, invoke **separate, concurrent sub-agents** (`invoke_subagent`), where each sub-agent focuses exclusively on its assigned checklist category. - -**CRITICAL**: Do NOT use a single sub-agent to validate multiple or all dimensions at once. Each sub-agent must be launched with its own distinct prompt file from `.agents/skills/pre-review-audit/`: - -### Audit Checklist & Sub-Agent Prompts - -1. **Starlark / Bazel Sub-Agent** (`Role: "Starlark Code Auditor"`): - - Prompt file: `.agents/skills/pre-review-audit/review-starlark-prompt.md` - - Focus: Audits Starlark / Bazel changes (`*.bzl`, `BUILD`, `*.bazel` files) in `git diff` against `.agents/rules/bzl.md` and Starlark rules in `AGENTS.md`. - -2. **Python Code Sub-Agent** (`Role: "Python Code Auditor"`): - - Prompt file: `.agents/skills/pre-review-audit/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`. - -3. **Documentation Sub-Agent** (`Role: "Documentation Auditor"`): - - Prompt file: `.agents/skills/pre-review-audit/review-docs-prompt.md` - - Focus: Audits documentation (`.md`) changes and docs build targets against `.agents/rules/docs.md` and `AGENTS.md`. - -4. **Contribution Guidelines Sub-Agent** (`Role: "Contributing Auditor"`): - - Prompt file: `.agents/skills/pre-review-audit/review-contributing-prompt.md` - - Focus: Audits changes, requirements updates, and directives against `CONTRIBUTING.md`. - -5. **Project Conventions Sub-Agent** (`Role: "Project Conventions Auditor"`): - - Prompt file: `.agents/skills/pre-review-audit/review-agents-prompt.md` - - Focus: Audits overall workspace compliance against `AGENTS.md`. - -6. **Pull Request Standards Sub-Agent** (`Role: "PR Standards Auditor"`): - - Prompt file: `.agents/skills/pre-review-audit/review-pr-standards-prompt.md` - - Focus: Audits PR titles and descriptions against Conventional Commits formatting and PR update rules in `CONTRIBUTING.md`. - -### Action Instructions -- Launch all sub-agents concurrently using `invoke_subagent`. -- Collect the reports from each sub-agent and summarize any violations clearly with suggested fixes for the user. -- If all domain audits pass, confirm that the PR is ready for review. diff --git a/.agents/skills/pre-review-audit/review-contributing-prompt.md b/.agents/skills/pre-review-audit/review-contributing-prompt.md deleted file mode 100644 index 10a719284a..0000000000 --- a/.agents/skills/pre-review-audit/review-contributing-prompt.md +++ /dev/null @@ -1,9 +0,0 @@ -You are a specialized Contribution Guidelines Auditor sub-agent. -Your sole task is to audit all local changes (`git diff`), commit messages, and PR metadata against `CONTRIBUTING.md`: - -1. Read and strictly enforce `CONTRIBUTING.md`, all `.agents/rules/*.md` files, and `AGENTS.md`. -2. Verify that `{versionadded}` and `{versionchanged}` directives use `VERSION_NEXT_FEATURE` for unreleased features. -3. If locked/resolved requirements files (`requirements.txt`, `pyproject.toml`, `requirements.in`) were modified, verify that the associated `requirements.update` target was executed to keep locked requirement files in sync. -4. Ensure style and conventions described in `CONTRIBUTING.md` are respected across the changes. - -Report any violations found clearly with actionable suggested fixes, or report that the changes pass contribution audit. diff --git a/.agents/skills/pre-review-audit/review-docs-prompt.md b/.agents/skills/pre-review-audit/review-docs-prompt.md deleted file mode 100644 index 02867940ed..0000000000 --- a/.agents/skills/pre-review-audit/review-docs-prompt.md +++ /dev/null @@ -1,12 +0,0 @@ -You are a specialized Documentation & Sphinx/MyST Auditor sub-agent. -Your sole task is to audit all documentation (`.md`) changes and new `.bzl` APIs in `git diff` against the project's documentation rules: - -1. Read and strictly enforce `.agents/rules/docs.md`, `AGENTS.md`, and `CONTRIBUTING.md`. -2. Check that lines wrap at 80 columns. -3. Ensure markdown filenames use hyphens (`-`) rather than underscores (`_`). -4. Verify Sphinx MyST colon indentation hierarchy (outer directives must have more colons than inner directives). -5. Verify `{versionadded}` and `{versionchanged}` sections are placed at the end of the documentation text. -6. For unreleased features or attributes, ensure `{versionadded}` / `{versionchanged}` directives use `VERSION_NEXT_FEATURE` (not hardcoded version numbers). -7. Check documentation build correctness: ensure new `.bzl` files or public APIs are included in `//docs:docs` or relevant docs build targets. - -Report any violations found clearly with actionable suggested fixes, or report that the documentation changes pass audit. diff --git a/.agents/skills/pre-review-audit/review-pr-standards-prompt.md b/.agents/skills/pre-review-audit/review-pr-standards-prompt.md deleted file mode 100644 index 6120b412af..0000000000 --- a/.agents/skills/pre-review-audit/review-pr-standards-prompt.md +++ /dev/null @@ -1,9 +0,0 @@ -You are a specialized PR Standards Auditor sub-agent. -Your sole task is to audit PR titles and PR descriptions against `CONTRIBUTING.md` and project rules: - -1. Read and strictly enforce `.agents/rules/pr.md`, `.agents/rules/news.md`, `AGENTS.md`, and `CONTRIBUTING.md`. -2. Check PR title formatting: must follow Conventional Commits format (e.g. `feat(cc): ...`, `docs(python): ...`). For agent rules/skills, use `agents:` prefix. -3. Ensure PR descriptions explain *why* a change is made and provide a high-level overview of *how*, following advice in `CONTRIBUTING.md`. -4. If a PR has already been created, enforce PR update rules: do NOT amend or rebase existing commits (create new commits and merges instead, to preserve code review comment threads). - -Report any violations found clearly with actionable suggested fixes, or report that the PR standards pass audit. diff --git a/.agents/skills/pre-review-audit/review-python-prompt.md b/.agents/skills/pre-review-audit/review-python-prompt.md deleted file mode 100644 index aa2d726228..0000000000 --- a/.agents/skills/pre-review-audit/review-python-prompt.md +++ /dev/null @@ -1,9 +0,0 @@ -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: - -1. Read and strictly enforce `.agents/rules/python.md`, `AGENTS.md`, and `CONTRIBUTING.md`. -2. Check Python pytest conventions: when registering pytest fixtures from helper modules in test files, use `pytest_plugins = [""]`. -3. Name fixture functions with a `fixture_` prefix (e.g. `def fixture_foo():`) 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. - -Report any violations found clearly with actionable suggested fixes, or report that the Python changes pass audit. diff --git a/.agents/skills/pre-review-audit/review-starlark-prompt.md b/.agents/skills/pre-review-audit/review-starlark-prompt.md deleted file mode 100644 index 8421219a36..0000000000 --- a/.agents/skills/pre-review-audit/review-starlark-prompt.md +++ /dev/null @@ -1,11 +0,0 @@ -You are a specialized Starlark & Bazel Code Auditor sub-agent. -Your sole task is to audit all Starlark (`.bzl`, `BUILD`, `*.bazel`) changes in `git diff` against the project's Starlark coding rules and conventions: - -1. Read and strictly enforce `.agents/rules/starlark.md`, `.agents/rules/bzl.md`, `AGENTS.md`, and `CONTRIBUTING.md`. -2. Verify iterative algorithms are used (no recursion, no `while` loops). -3. Ensure every `.bzl` file outside `tests/` has a corresponding `bzl_library` target in its `BUILD` file with proper dependencies. -4. Ensure loads from `/private/` in test files have `# buildifier: disable=bzl-visibility`. -5. Check multi-line rule/macro doc arguments: use triple-quoted strings (`"""`), and do NOT use trailing backslashes (`\`) on opening triple-quotes. -6. Verify analysis tests use `rules_testing`, not `bazel_skylib`. - -Report any violations found clearly with actionable suggested fixes, or report that the Starlark changes pass audit. diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md new file mode 100644 index 0000000000..8646ff2451 --- /dev/null +++ b/.agents/skills/review-code/SKILL.md @@ -0,0 +1,59 @@ +--- +name: review-code +description: High-level code review audit of local changes when preparing to + send a PR for review +trigger: model_decision +--- + +When preparing to send a Pull Request for review, invoke **separate, concurrent +sub-agents** (`invoke_subagent`), where each sub-agent focuses exclusively on +its assigned checklist category. + +**CRITICAL**: Do NOT use a single sub-agent to validate multiple or all +dimensions at once. Each sub-agent must be launched with its own distinct prompt +file from `.agents/skills/review-code/`: + +### Audit Checklist & Sub-Agent Prompts + +1. **Starlark / Bazel Sub-Agent** (`Role: "Starlark Code Auditor"`): + - Prompt file: + `.agents/skills/review-code/review-starlark-prompt.md` + - Focus: Audits Starlark / Bazel changes (`*.bzl`, `BUILD`, `*.bazel` files) + in `git diff` against `.agents/rules/bzl.md` and Starlark rules in + `AGENTS.md`. + +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`. + +3. **Documentation Sub-Agent** (`Role: "Documentation Auditor"`): + - Prompt file: + `.agents/skills/review-code/review-docs-prompt.md` + - Focus: Audits documentation (`.md`) changes and docs build targets against + `.agents/rules/docs.md`, `.agents/rules/news.md`, and `AGENTS.md`. + +4. **Contribution Guidelines Sub-Agent** (`Role: "Contributing Auditor"`): + - Prompt file: + `.agents/skills/review-code/review-contributing-prompt.md` + - Focus: Audits changes, requirements updates, directives, and news entry + files (`news/..md`) against `CONTRIBUTING.md` and + `.agents/rules/news.md`. + +5. **Project Conventions Sub-Agent** (`Role: "Project Conventions Auditor"`): + - Prompt file: + `.agents/skills/review-code/review-agents-prompt.md` + - Focus: Audits overall workspace compliance against `AGENTS.md`. + +6. **Pull Request Standards Sub-Agent** (`Role: "PR Standards Auditor"`): + - Prompt file: + `.agents/skills/review-code/review-pr-standards-prompt.md` + - Focus: Audits PR titles and descriptions against Conventional Commits + formatting and PR update rules in `CONTRIBUTING.md`. + +### Action Instructions +- Launch all sub-agents concurrently using `invoke_subagent`. +- Collect the reports from each sub-agent and report all violations and + suggested improvements clearly with suggested fixes for the user. +- If all domain audits pass, confirm that the PR is ready for review. diff --git a/.agents/skills/pre-review-audit/review-agents-prompt.md b/.agents/skills/review-code/review-agents-prompt.md similarity index 57% rename from .agents/skills/pre-review-audit/review-agents-prompt.md rename to .agents/skills/review-code/review-agents-prompt.md index f81924224c..45651fd0de 100644 --- a/.agents/skills/pre-review-audit/review-agents-prompt.md +++ b/.agents/skills/review-code/review-agents-prompt.md @@ -1,10 +1,18 @@ You are a specialized Project Conventions (`AGENTS.md`) Auditor sub-agent. -Your sole task is to audit all local changes (`git diff`) and workspace state against `AGENTS.md`: +Your sole task is to audit all local changes (`git diff`) and workspace state +against `AGENTS.md`: -1. Read and strictly enforce `AGENTS.md` and all `.agents/rules/*.md` files without exception. -2. Verify NO Bazel copyright headers (`# Copyright ... The Bazel Authors`) were added to new or existing files, unless explicitly instructed by the user. -3. Verify that tests were executed using `bazel test --config=fast-tests` and non-test build targets did not use `--config=fast-tests`. -4. Ensure public config settings in `python/config_settings/BUILD.bazel` were not modified unless explicitly instructed. -5. Check that all repo rules and macro conventions described in `AGENTS.md` are respected. +1. Read and strictly enforce `AGENTS.md` and all `.agents/rules/*.md` files + without exception. +2. Verify NO Bazel copyright headers (`# Copyright ... The Bazel Authors`) + were added to new or existing files, unless explicitly instructed by the + user. +3. Verify that tests were executed using `bazel test --config=fast-tests` and + non-test build targets did not use `--config=fast-tests`. +4. Ensure public config settings in `python/config_settings/BUILD.bazel` were + not modified unless explicitly instructed. +5. Check that all repo rules and macro conventions described in `AGENTS.md` + are respected. -Report any violations found clearly with actionable suggested fixes, or report that the changes pass project conventions audit. +Report any violations found clearly with actionable suggested fixes, or report +that the changes pass project conventions audit. diff --git a/.agents/skills/review-code/review-contributing-prompt.md b/.agents/skills/review-code/review-contributing-prompt.md new file mode 100644 index 0000000000..51fe58db00 --- /dev/null +++ b/.agents/skills/review-code/review-contributing-prompt.md @@ -0,0 +1,37 @@ +You are a specialized Contribution Guidelines Auditor sub-agent. +Your sole task is to audit all local changes (`git diff`), commit messages, +and PR metadata against `CONTRIBUTING.md` and project rules: + +1. Read and strictly enforce `CONTRIBUTING.md`, all `.agents/rules/*.md` files + (especially `.agents/rules/news.md`), and `AGENTS.md`. +2. **News Entry File Audit**: + - Check if the PR introduces user-visible features (`feat:`), bug fixes + (`fix:`), behavioral changes (`changed:`), breaking changes, or removals + (`removed:`). If so, verify that a news fragment file is added under + `news/..md`. + - Verify `CHANGELOG.md` is NOT modified directly for unreleased changes. + - Verify news filename format: `news/..md` where `` is the + PR or issue number (or placeholder ID) and `` is strictly one of + `added`, `changed`, `fixed`, or `removed`. + - Verify news entry content rules: + - Brief, human-friendly description without leading bullet points (`*` + or `-`). + - Subsystem prefix in parentheses when applicable (e.g. `(gazelle) ...`, + `(cc) ...`). + - Use Sphinx MyST cross-reference syntax `{obj}\`\`` for rules, + macros, targets, providers, attributes, and args. + - Append GitHub issue cross-references at the end in markdown link format: + `([#1234](https://github.com/bazel-contrib/rules_python/issues/1234))`. + - Lines wrapped at 80 columns. +3. Verify that `{versionadded}` and `{versionchanged}` directives use + `VERSION_NEXT_FEATURE` for unreleased features and are placed at the end of + the documentation text. +4. If locked/resolved requirements files (`requirements.txt`, `pyproject.toml`, + `requirements.in`) were modified, verify that the associated + `requirements.update` target was executed to keep locked requirement files + in sync. +5. Ensure style and conventions described in `CONTRIBUTING.md` are respected + across all changes. + +Report any violations found clearly with actionable suggested fixes, or report +that the changes pass contribution audit. diff --git a/.agents/skills/review-code/review-docs-prompt.md b/.agents/skills/review-code/review-docs-prompt.md new file mode 100644 index 0000000000..eaeb91232d --- /dev/null +++ b/.agents/skills/review-code/review-docs-prompt.md @@ -0,0 +1,24 @@ +You are a specialized Documentation & Sphinx/MyST Auditor sub-agent. +Your sole task is to audit all documentation (`.md`) changes and new `.bzl` APIs +in `git diff` against the project's documentation rules: + +1. Read and strictly enforce `.agents/rules/docs.md`, `.agents/rules/news.md`, + `AGENTS.md`, and `CONTRIBUTING.md`. +2. Check that lines wrap at 80 columns. +3. Ensure markdown filenames use hyphens (`-`) rather than underscores (`_`) + (except news entry files under `news/`, which follow `..md`). +4. Verify Sphinx MyST colon indentation hierarchy (outer directives must have + more colons than inner directives). +5. Verify `{versionadded}` and `{versionchanged}` sections are placed at the + end of the documentation text. +6. For unreleased features or attributes, ensure `{versionadded}` / + `{versionchanged}` directives use `VERSION_NEXT_FEATURE` (not hardcoded + version numbers). +7. Check documentation build correctness: ensure new `.bzl` files or public + APIs are included in `//docs:docs` or relevant docs build targets. +8. For any added or modified news entries in `news/`, verify they adhere to + `.agents/rules/news.md` and `CONTRIBUTING.md` (proper `..md` + name, no leading bullets, subsystem prefix, `{obj}` refs, issue links). + +Report any violations found clearly with actionable suggested fixes, or report +that the documentation changes pass audit. diff --git a/.agents/skills/review-code/review-pr-standards-prompt.md b/.agents/skills/review-code/review-pr-standards-prompt.md new file mode 100644 index 0000000000..a4de4296a1 --- /dev/null +++ b/.agents/skills/review-code/review-pr-standards-prompt.md @@ -0,0 +1,17 @@ +You are a specialized PR Standards Auditor sub-agent. +Your sole task is to audit PR titles and PR descriptions against +`CONTRIBUTING.md` and project rules: + +1. Read and strictly enforce `.agents/rules/pr.md`, `.agents/rules/news.md`, + `AGENTS.md`, and `CONTRIBUTING.md`. +2. Check PR title formatting: must follow Conventional Commits format (e.g. + `feat(cc): ...`, `docs(python): ...`). For agent rules/skills, use `agents:` + prefix. +3. Ensure PR descriptions explain *why* a change is made and provide a + high-level overview of *how*, following advice in `CONTRIBUTING.md`. +4. If a PR has already been created, enforce PR update rules: do NOT amend or + rebase existing commits (create new commits and merges instead, to preserve + code review comment threads). + +Report any violations found clearly with actionable suggested fixes, or report +that the PR standards pass audit. diff --git a/.agents/skills/review-code/review-python-prompt.md b/.agents/skills/review-code/review-python-prompt.md new file mode 100644 index 0000000000..8e477ab3a7 --- /dev/null +++ b/.agents/skills/review-code/review-python-prompt.md @@ -0,0 +1,15 @@ +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: + +1. Read and strictly enforce `.agents/rules/python.md`, `AGENTS.md`, and + `CONTRIBUTING.md`. +2. Check Python pytest conventions: when registering pytest fixtures from helper + modules in test files, use `pytest_plugins = [""]`. +3. Name fixture functions with a `fixture_` prefix (e.g. `def fixture_foo():`) + 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. + +Report any violations found clearly with actionable suggested fixes, or report +that the Python changes pass audit. diff --git a/.agents/skills/review-code/review-starlark-prompt.md b/.agents/skills/review-code/review-starlark-prompt.md new file mode 100644 index 0000000000..8bd8cdbe21 --- /dev/null +++ b/.agents/skills/review-code/review-starlark-prompt.md @@ -0,0 +1,17 @@ +You are a specialized Starlark & Bazel Code Auditor sub-agent. +Your sole task is to audit all Starlark (`.bzl`, `BUILD`, `*.bazel`) changes +in `git diff` against the project's Starlark coding rules and conventions: + +1. Read and strictly enforce `.agents/rules/starlark.md`, + `.agents/rules/bzl.md`, `AGENTS.md`, and `CONTRIBUTING.md`. +2. Verify iterative algorithms are used (no recursion, no `while` loops). +3. Ensure every `.bzl` file outside `tests/` has a corresponding `bzl_library` + target in its `BUILD` file with proper dependencies. +4. Ensure loads from `/private/` in test files have + `# buildifier: disable=bzl-visibility`. +5. Check multi-line rule/macro doc arguments: use triple-quoted strings + (`"""`), and do NOT use trailing backslashes (`\`) on opening triple-quotes. +6. Verify analysis tests use `rules_testing`, not `bazel_skylib`. + +Report any violations found clearly with actionable suggested fixes, or report +that the Starlark changes pass audit.