agents: enforce concise prose and refine PR skills (#4241) Agent rules and skills often accumulate mannered, verbose prose that wastes context. Additionally, PR review and merge skills lacked merge-base diffing and explicit upstream repository targeting. Add a glob-triggered rule and update `rule-creator` to enforce concise Strunk & White prose across agent configurations. Update `review-code` to diff against the `upstream/main` merge-base, and update `merge-pr` to target `bazel-contrib/rules_python` and clarify immediate-merge consent.
diff --git a/.agents/rules/agent-config.md b/.agents/rules/agent-config.md new file mode 100644 index 0000000..f169329 --- /dev/null +++ b/.agents/rules/agent-config.md
@@ -0,0 +1,12 @@ +--- +trigger: glob +description: Prose style rules for agent configs, rules, and skills +globs: ".agents/**/*.md,AGENTS.md,GEMINI.md" +--- + +# Agent Configuration Style + +* Write in concise Strunk & White prose: omit needless words, use active voice, + and state imperatives directly. +* Do not use mannered prose, filler phrases, or verbose explanations. +* Wrap lines at 80 columns.
diff --git a/.agents/skills/merge-pr/SKILL.md b/.agents/skills/merge-pr/SKILL.md index 399b329..e611e64 100644 --- a/.agents/skills/merge-pr/SKILL.md +++ b/.agents/skills/merge-pr/SKILL.md
@@ -1,18 +1,23 @@ --- name: merge-pr -description: Merge a pull request into main, monitoring the merge queue, retrying CI flakes, and re-enqueuing if necessary +description: Merge a pull request into main, monitoring the merge queue, + retrying CI flakes, and re-enqueuing if necessary --- -When the user asks to merge a pull request (e.g., "merge PR <number>", "merge this PR", or monitor its merge): +When the user asks to merge a pull request (e.g., "merge PR <number>", "merge +this PR", or monitor its merge): -1. **Enqueue for Merge**: Run `gh pr merge <pr_number> --auto --squash` to enable auto-merge or add the pull request to the merge queue. - - **Force / Admin Merge**: **CRITICAL**: Passing `--admin` to bypass the - merge queue or required checks requires explicit user permission or - consent. Only pass `--admin` (e.g., `gh pr merge <pr_number> --admin - --squash`) if the user has explicitly requested or approved a force/admin - merge. Never invoke `--admin` autonomously. -2. **Invoke a Background Shepherd**: Launch a background subagent with the role `Merge PR Shepherd` to continuously watch the PR until it merges. -3. **Leverage Existing CI Skills**: +1. **Enqueue for Merge**: Run + `gh pr merge <pr_number> --repo bazel-contrib/rules_python --auto --squash`. + - **Force / Admin Merge**: **CRITICAL**: Only pass `--admin` (e.g., + `gh pr merge <pr_number> --repo bazel-contrib/rules_python --admin + --squash`) with explicit user consent ("force merge", "admin merge", or + "merge immediately" once CI passes and only `REVIEW_REQUIRED` blocks). + Never pass `--admin` while CI is pending or failing unless told to bypass + CI. +2. **Invoke a Background Shepherd**: Launch a background subagent with the role + `Merge PR Shepherd` to continuously watch the PR until it merges. +3. **Leverage Existing CI Skills**: - Have the subagent use the **`monitor-ci-results`** skill to watch for CI check failures and generate analysis reports. - Have the subagent use the **`buildkite-retry-job`** skill @@ -22,12 +27,16 @@ - **Soft-Failing Jobs**: Experimental Buildkite jobs (e.g. `*rolling*` Bazel) are non-blocking soft failures; do not treat them as merge blockers. - When the PR is queued, actively discover the merge queue branch via - `gh api repos/:owner/:repo/branches --jq '.[].name | select(test("gh-readonly-queue/.*/pr-<pr_number>-"))'` + `gh api repos/:owner/:repo/branches --jq` with + `'.[].name | select(test("gh-readonly-queue/.*/pr-<pr_number>-"))'` and monitor commit statuses/Buildkite builds running on that temporary branch. -4. **Queue Shepherding**: Periodically check `gh pr view <pr_number> --json +4. **Queue Shepherding**: Periodically check + `gh pr view <pr_number> --repo bazel-contrib/rules_python --json state,autoMergeRequest,mergeStateStatus,mergeable`. While `state` is `"OPEN"`, if `autoMergeRequest` is `null` and no `gh-readonly-queue/.*/pr-<pr_number>-` branch exists, re-enqueue with - `gh pr merge <pr_number> --auto --squash` once checks are green. -5. **Completion Notification**: Once `state` becomes `"MERGED"`, send a high-priority message back to the parent conversation. + `gh pr merge <pr_number> --repo bazel-contrib/rules_python --auto --squash` + once checks are green. +5. **Completion Notification**: Once `state` becomes `"MERGED"`, send a + high-priority message back to the parent conversation.
diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index f53116c..38f7bbb 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md
@@ -63,6 +63,9 @@ - Immediately create a user-facing review artifact named `code-review-results.md` in the conversation artifact directory so progress is visible right away. +- Have sub-agents run `git diff $(git merge-base HEAD upstream/main)` to audit + committed and uncommitted branch changes without newer `upstream/main` + commits. - Launch all sub-agents concurrently using `invoke_subagent`. - Update `code-review-results.md` as sub-agent responses come in. - The artifact must include:
diff --git a/.agents/skills/rule-creator/SKILL.md b/.agents/skills/rule-creator/SKILL.md index 1d0f9cd..34306e7 100644 --- a/.agents/skills/rule-creator/SKILL.md +++ b/.agents/skills/rule-creator/SKILL.md
@@ -1,6 +1,7 @@ --- name: rule-creator -description: Create and format agent rules with proper front matter in the workspace +description: Create and format agent rules with proper front matter in the + workspace --- Use this skill when you need to create a new rule for the agent in the @@ -35,11 +36,9 @@ applies in certain contexts. ### Formatting Guidelines -* **Line Wrapping:** Always wrap all text in the rule file (including the - title and description) to **80 columns** to ensure readability and - compatibility. -* **Conciseness (Strunk & White):** Omit needless words. Write brief, direct, - actionable directives without filler prose. +* **Line Wrapping:** Wrap all text to 80 columns. +* **Prose Style (Strunk & White):** Omit needless words. Do not use mannered + prose or verbose phrasing; state directives directly in active voice. ### Example