From a6f38386e94277c19cdfd2ffd89700448dc3fe61 Mon Sep 17 00:00:00 2001 From: Richard Levasseur Date: Sat, 8 Aug 2026 20:53:53 +0000 Subject: [PATCH] agents: optimize rules and clarify create-pr subagent requirements Agent rule and skill definitions contained redundant prose and missed actionable guardrails for argparse attribute access, workflow input handling, and interactive PR draft linking. Streamline python.md and github_actions_workflows.md rules for token efficiency, add explicit conventions for argparse attributes and workflow inputs, and strengthen create-pr skill delegation instructions while ensuring draft artifacts are linked before requesting confirmation. --- .agents/rules/github_actions_workflows.md | 6 +- .agents/rules/python.md | 13 +++-- .agents/skills/create-pr/SKILL.md | 67 +++++++++-------------- 3 files changed, 38 insertions(+), 48 deletions(-) diff --git a/.agents/rules/github_actions_workflows.md b/.agents/rules/github_actions_workflows.md index 29bf628a24..525d2a2699 100644 --- a/.agents/rules/github_actions_workflows.md +++ b/.agents/rules/github_actions_workflows.md @@ -6,5 +6,7 @@ globs: [".github/workflows/*.yml", ".github/workflows/*.yaml", ".github/*.yaml"] # GitHub Actions Workflows Rule -* When creating files in `.github/workflows/` (such as `.yml` or `.yaml` - files), always use the latest version of the referenced GitHub Actions. +* Use the latest version of referenced actions in `.github/workflows/`. +* Preserve `suppress-no-jobs-ran-error` fallback jobs in conditional workflows. +* Pass inputs (e.g. `${{ inputs.issue }}`) directly to commands without + redundant shell parameter stripping or conversions. diff --git a/.agents/rules/python.md b/.agents/rules/python.md index 523cc923cd..22221fe3a1 100644 --- a/.agents/rules/python.md +++ b/.agents/rules/python.md @@ -1,8 +1,11 @@ # Python Conventions ## pytest -* **Fixture Registration via `pytest_plugins`**: When registering pytest helper - modules in test files, use `pytest_plugins = [""]`. -* **Fixture Naming Conventions**: Name fixture functions with a `fixture_` prefix - (e.g. `def fixture_foo():`), and pass the public fixture name using the `name` - parameter in `@pytest.fixture(name="foo")`. +* Register helper fixtures using `pytest_plugins = [""]`. +* Name fixture functions with `fixture_` prefix and pass public name via + `@pytest.fixture(name="foo")`. + +## CLI & Arguments +* Use direct attribute access (e.g. `args.foo`) on `argparse.Namespace` with + well-defined shapes. Avoid defensive `getattr()`. + diff --git a/.agents/skills/create-pr/SKILL.md b/.agents/skills/create-pr/SKILL.md index 88b687b39f..97abf1d467 100644 --- a/.agents/skills/create-pr/SKILL.md +++ b/.agents/skills/create-pr/SKILL.md @@ -4,51 +4,36 @@ description: Propose, draft, or create a pull request by delegating to a subagent --- -When creating a Pull Request for local changes or a branch, invoke a subagent -to handle PR creation or description drafting. +When proposing, drafting, or creating a Pull Request, you MUST ALWAYS delegate +to a subagent. NEVER create or draft PRs directly in the main conversation. ### Instructions -1. **Pre-Review Audit Subagent**: Before drafting or creating a PR, launch a - subagent to run the `pre-review-audit` skill on local changes (`git diff`). - Verify all checks pass (e.g., `VERSION_NEXT_FEATURE` directives, no Bazel - copyright headers, line wrapping, Starlark formatting). Fix any issues - found before proceeding. -2. Launch a subagent using `invoke_subagent` with `TypeName: "self"` (or - `agentapi new-conversation`). -3. Provide a prompt to the subagent directing it to: - - Include `@/.agents/rules/pr.md` and read `CONTRIBUTING.md` (specifically - the sections on **Commit messages and PR descriptions** and - **Documenting changes**) before drafting. - - Strictly adhere to `CONTRIBUTING.md` rules for: - - **PR Title**: Follow conventional commit style and title formatting. - For agent rules, skills, and system updates, use `agents:` prefix. - - **PR Body**: Include rationale, high-level summary, and structure. - **CRITICAL**: Strictly wrap all PR body text at 72 columns max - (GitHub uses the PR description as the commit message upon merge, - which reflows text at 72 columns). - - **Formatting**: Follow repository style guidelines and structure. - - Create a Markdown artifact (`pr_info.md`) meeting the following requirements: - - **User-facing**: Published so it is presented directly in the user interface. - - **Interactive feedback enabled**: Allows the user to select lines and leave inline comments on the draft. - - **User decision choices**: Ask the user if they want to: +1. **Pre-Review Audit**: Launch a subagent with `pre-review-audit` to verify + `git diff` conforms to all rules (line wrapping, copyright, conventions). +2. **Launch Subagent**: Use `invoke_subagent` (`TypeName: "self"`). +3. **Subagent Prompt Instructions**: + - Follow `CONTRIBUTING.md` and `@/.agents/rules/pr.md`. + - **PR Title**: Conventional commits format (`agents:` prefix for agent + rules/skills). + - **PR Body**: Explain *why* and conceptual *how*. Wrap strictly at 72 + columns max. Omit TAG/CONV. + - **Artifact Requirements**: Create `pr_info.md` with: + - **User-facing**: Published directly in the user interface. + - **Interactive feedback enabled**: Allows selecting lines and leaving + inline comments on the draft (`RequestFeedback: true`). + - **User decision choices**: Present choices: 1. Create a regular PR 2. Create a draft PR 3. Provide feedback on the draft text 4. Discard the draft text - - **Propose vs. Create**: If the user requested to propose or draft a PR - description, **do not** run `gh pr create`—just create the `pr_info.md` - artifact for the user to review. Otherwise, execute `gh pr create` with - the formatted title and body. - - **Targeting Upstream Repo**: When executing `gh pr create`, always target - the upstream repository by passing `--repo bazel-contrib/rules_python` and - `--head :`. -4. **Return Status**: Direct the subagent to communicate the PR number or draft - status back using `send_message` (or `agentapi send-message`) with the - parent conversation ID, or include it in its final completion response. -5. **Publish Artifact**: Upon receiving the subagent completion message, the - main agent must publish `pr_info.md` to display the artifact directly in - the primary user UI. -6. **Interactive Actions**: To present custom action choices to the user - (e.g., "Create PR", "Create Draft PR"), the main agent can use the - `ask_question` tool with custom options. + - **Propose vs. Create**: If proposing or drafting a PR, do NOT run + `gh pr create`—only create the `pr_info.md` artifact. Only execute + `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. +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.