# Review pull requests with owners policies

This agent risk-tiers every pull request in your repository, requests
the owners as reviewers, and approves what your policy allows. Rules
live in `.agentic-owners/policy.yml` files at any depth. The closest policy to a changed file wins. The agent reads
policies from the PR's base ref, so a PR can't exempt itself.

## Scaffold and run

```bash
agent-sdk init ./owners-agent --template agentic-owners
```

Set your repositories in `bot/lib/config.ts` (`repos: ["acme/api"]`),
then run:

```bash
cd owners-agent
agent-sdk login
agent-sdk dev
```

PR events stream through your Cursor account, so you don't need a
webhook or GitHub App. The agent reviews a PR when it's opened,
reopened, pushed to, marked ready for review, or retargeted, and skips
drafts. Open a PR or replay a real one:

```bash
agent-sdk github replay https://github.com/acme/api/pull/123 --dir .
```

Deploy with `agent-sdk deploy`.

## Policies

With no policy files, the agent approves very-low and low risk PRs and
holds medium and above with a comment. Commit policies to route
reviews:

```yaml
# .agentic-owners/policy.yml at any depth; the closest policy wins.
version: 1
policies:
  - 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 must
```

`paths` are relative to the policy's parent directory, so
`src/.agentic-owners/policy.yml` matches `api/**` against `src/api/**`.
A leading `../` reaches a sibling tree inside the repo.

| Key | Meaning |
| --- | --- |
| `paths` | Required globs |
| `team`, `teams` | Owner teams, as a slug in the repo's org or an `org/team` handle |
| `user`, `users` | Owner GitHub logins, without `@` |
| `prompt` | Extra rubric file beside the policy |
| `mode` | `advisory`, the default, approves low risk. `hard` requires a person to approve. `notify` never blocks and doesn't request its owners |
| `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. Allows no other key except `paths` |

- A rule without owners must set `always_approve: true`.
- `global_exclusions` in the root policy opts paths out entirely.
- The template rejects `delegated_automations`.

## What one review does

- One model turn per PR head grades the diff against the base rubric
  and matched rule prompts, then calls `record_review` with `very_low`,
  `low`, `medium`, `medium_high`, or `high`. The model never writes to
  GitHub.
- The host recomputes the policy from trusted state. It approves when
  every matched rule is `always_approve` or `notify`. Otherwise it
  approves only when the author's `self_review` clears every matched
  `hard` rule at very low or low risk, or every rule that can require
  review at medium and above.
- When the agent holds, it requests up to two owners, never the author,
  and updates one status comment in place.
- An approval binds to the head SHA. A later hold dismisses the agent's
  earlier approvals.
- The agent holds when the PR edits `.agentic-owners/` or `CODEOWNERS`,
  or when the diff is empty or GitHub truncated the diff or file list.
  `self_review` never clears a governance edit.
- A broken policy file fails closed and comments with the validation
  issues.

## Rubric

Edit `bot/lib/owners/prompts/base-review.md` to change the risk tiers.
Put per-area guidance in policy `prompt:` files.

## Evals

`agent-sdk eval` runs three smoke reviews without writing to GitHub.
They cover a docs-only change, an auth deletion, and a prompt injection.
