Review pull requests with owners policies
This agent reviews every pull request in your repository. It risk-tiers
the diff, requests the owning team or user as reviewers, and approves
what your policy allows. Ownership rules live in
.agentic-owners/policy.yml files committed at any depth of the repo.
The closest policy to a changed file wins, and policies are always read
from the PR's base ref, so a PR cannot exempt itself.
Scaffold
agent-sdk init ./owners-agent --template agentic-ownersinit writes the project, installs dependencies, and puts agent-sdk
on PATH.
Log in and run
Set your repositories in bot/lib/config.ts (repos: ["acme/api"]),
then:
cd owners-agentagent-sdk loginagent-sdk devPR events stream through your Cursor account. No webhook or GitHub App
setup. The agent reviews a PR when it is opened, reopened, pushed to,
marked ready for review, or retargeted to another base. Draft PRs wait
until they are ready. Open a PR, or replay a real one (this also works
with repos empty):
agent-sdk github replay https://github.com/acme/api/pull/123 --dir .Deploy with agent-sdk deploy.
Policies
With no policy files, every PR gets a default risk review: very-low and low risk approve, medium and above hold with a comment. Route reviews by committing policies:
# .agentic-owners/policy.yml at any depth; the closest policy wins.version: 1policies: - paths: ["docs/**"] always_approve: true - paths: ["src/api/**"] team: platform # bare slug in the repo's org; or acme/platform, or user: alice prompt: api-review.md # optional extra rubric, same directory - paths: ["src/billing/**"] users: [alice, bob] mode: hard # the agent never approves; a person mustpaths are globs relative to the directory that holds the
.agentic-owners/ folder, so a root policy sees repo-relative paths and
src/.agentic-owners/policy.yml matches api/** against
src/api/**. Leading ../ segments reach a sibling tree. A path cannot
escape the repo.
| Key | Meaning |
|---|---|
paths | Globs relative to the policy's directory. Required. |
team / teams | Owner teams. A bare slug resolves in the repo's org. An org/team handle names a team directly. |
user / users | Owner GitHub logins, without @. |
prompt | Markdown filename in the same directory, added to the rubric for matching PRs. |
mode | advisory (default): low risk approves. hard: a person must approve. notify: the rule never blocks and its owners are not requested. |
human_review_required | true is the older spelling of mode: hard. |
self_review | A listed user: owner's own PRs clear this rule. |
always_approve | Satisfied at every risk tier. Cannot combine with owners, prompt, mode, self_review, or human_review_required. |
A rule without owners must set always_approve: true.
global_exclusions in the root policy opts paths out entirely. The
agent rejects delegated_automations: nothing in this template consumes
automation approvals.
What one review does
One model turn per PR head assesses the host-fetched diff against the
base rubric plus any matched rule prompts, then records a risk tier of
very_low, low, medium, medium_high, or high with
record_review. The host recomputes the policy from trusted state and
applies the deterministic decision:
- Approve when every matched rule is
always_approveornotify, or when the tier is very low or low and every matchedhardrule is cleared by an owner-author withself_review. At medium and above, the agent approves only when the author'sself_reviewcovers every rule that can require review. - Request reviewers otherwise: the policy owners (max 2, never the author), plus one status comment the agent keeps updated in place.
An approval binds to the head SHA, and a later hold dismisses the
agent's earlier approvals. The agent also holds when the PR edits
.agentic-owners/ or CODEOWNERS, when the diff is empty or truncated,
or when GitHub capped the changed-file list. self_review never clears
a governance edit.
The model never writes to GitHub. A broken policy file fails closed with
a comment listing the validation issues. Team membership is not
resolved, because repo-scoped credentials cannot read org teams, so
self_review applies to user: owners only.
Rubric
Edit bot/lib/owners/prompts/base-review.md for the risk tiers and
their boundaries. Per-area guidance belongs in policy prompt: files
next to the policy that names them. The next review reads both.
Evals
Use the three smoke reviews as a local exercise:
agent-sdk evalThe cases are a docs-only change, an auth deletion, and a prompt injection. Eval sessions skip GitHub writes.