diff --git a/AGENTS.md b/AGENTS.md index feabe9ed..21f91b62 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,6 +25,7 @@ - [Linking tracker issues and PRs](#linking-tracker-issues-and-prs) - [Mentioning project maintainers and security-team members](#mentioning-project-maintainers-and-security-team-members) - [Reusable skills](#reusable-skills) + - [Reviewing pull requests](#reviewing-pull-requests) - [Keeping evals and mode-economics in sync](#keeping-evals-and-mode-economics-in-sync) - [When the rule fires](#when-the-rule-fires) - [Before submitting](#before-submitting) @@ -917,6 +918,20 @@ When adding a new skill: - avoid agent-specific syntax so the skill remains portable across tools; - **ship a behavioural eval suite** under [`tools/skill-evals/evals//`](tools/skill-evals/) — see [Keeping evals and mode-economics in sync](#keeping-evals-and-mode-economics-in-sync). The [`write-skill`](skills/write-skill/SKILL.md) skill prompts for the capability frontmatter on every new-skill scaffold. A skill PR without a matching eval suite is incomplete. +### Reviewing pull requests + +For PR code review in this repo, use the +[`pr-management-code-review`](skills/pr-management-code-review/SKILL.md) +skill — not an ad-hoc review pass or a generic review command. It +anchors every finding as an **inline review comment** (`file:line`), +presents the drafted comments to the maintainer **individually for +accept/skip**, and posts the accepted set as a single review. A +body-only review is the explicit opt-out (`inline:off`), never the +default; findings that cannot be anchored to a changed line go in the +review body. Adopters that install the `pr-management-*` family inherit +the same default in their own `AGENTS.md` (wired by +[`skills/setup/adopt.md`](skills/setup/adopt.md)). + ## Keeping evals and mode-economics in sync When you change a skill or a tool adapter the skills load, two diff --git a/skills/pr-management-code-review/SKILL.md b/skills/pr-management-code-review/SKILL.md index bce75741..8bf1a0a7 100644 --- a/skills/pr-management-code-review/SKILL.md +++ b/skills/pr-management-code-review/SKILL.md @@ -509,12 +509,17 @@ For each PR in the list, run the per-PR review loop in [`posting.md#disposition`](posting.md), apply Golden rules 7 and 8, and produce a draft body using the templates in [`posting.md`](posting.md). -6. **Show the inline-comments picker** — for every anchored - finding the skill drafts an inline review comment and - presents them in a numbered list with all entries enabled - by default. The maintainer picks `[A]ll` / `[N]one` / - `[]` / drops a few. Suppressed for the whole - session if `inline:off` was passed. +6. **Show the inline-comments picker** — inline review + comments are the **default and preferred** output of this + skill: for every anchored finding the skill drafts an + inline review comment and presents them in a numbered list + with all entries enabled by default, so the maintainer + accepts them individually. The maintainer picks `[A]ll` / + `[N]one` / `[]` / drops a few. A body-only review + is the explicit exception, reached only by passing + `inline:off`, which suppresses the picker for the whole + session. Findings that cannot be anchored to a `file:line` + (e.g. on unchanged lines) go in the review body instead. 7. **Show the draft to the maintainer** — full body, count of inline comments to be posted, and the chosen disposition. 8. **On confirmation** — post via the GraphQL diff --git a/skills/setup/adopt.md b/skills/setup/adopt.md index e5f14097..927d7871 100644 --- a/skills/setup/adopt.md +++ b/skills/setup/adopt.md @@ -1120,6 +1120,24 @@ framework before they hit a "skill not found" error: [`apache/magpie`](https://github.com/apache/magpie). ``` + **If the adopter installed the `pr-management-*` family** + (Step 5), append the following subsection to the + `AGENTS.md` block above, so the adopter's agent defaults to + the framework's review skill. Skip it entirely for adopters + who did not take that family. + + ```markdown + ### Reviewing pull requests + + With apache-magpie installed locally, use the + `magpie-pr-management-code-review` skill for PR code + review. It posts findings as **inline review comments** + anchored to `file:line`, presented **individually for + accept/skip** before anything is submitted — prefer it + over an ad-hoc review pass or a generic review command. A + body-only review is the explicit opt-out (`inline:off`). + ``` + Do not create `AGENTS.md` if it does not already exist — the contributor-facing section in `README.md` is the authoritative entry-point, and an empty `AGENTS.md` would