Author a review.yml

Top-level keys

VeriFlow reads the file from .github/review.yml when a pull request is opened or marked ready for review, and merges it on top of the platform defaults. Anything you omit falls back to the documented default — so an empty file is valid and behaves like the minimum viable config below.

• version — schema version of the file; always 1 today.
• depth — how deep the agent reads the diff: summary, standard, or deep.
• paths — glob allowlist (or denylist with paths.ignore) that scopes the review to specific files.
• ignore — patterns the agent should skip even when paths allow them (lockfiles, generated code, vendored files).
• comments — controls how many inline comments the agent posts per file or per review.
• languages — per-language overrides that re-tune the keys above for one ecosystem.

Options reference

Every key, its default value, and what it actually does in the review loop. Defaults are what you get when the file is absent — listing them here makes it obvious what behaviour you're overriding.

version

Default: 1. Pins the schema version VeriFlow should parse against. Always set this to 1 today; the agent will refuse to load a higher number rather than assuming it understands a future schema.

depth

Default: standard. One of summary (top-of-file write-up only), standard (file-level summary plus targeted inline comments), or deep (line-by-line commentary with type and control-flow analysis). Higher depths cost more tokens and produce more PR noise — start at standard and step up only on PRs that need it.

paths

Default: ["**/*"]. Gitignore-flavored glob list. When non-empty, only files matched by at least one entry are reviewed; everything else is silently skipped. Use paths.ignore to carve holes in the allowlist — e.g. allow src/** but skip src/**/*.test.ts.

ignore

Default: []. Glob patterns of files to always skip — even when paths would let them through. The agent still writes a one-line note on the PR when files of this shape are touched, so reviewers see *something* is being skipped.

comments

Default: { per_file: 5, per_review: 40 }. Caps how many inline comments the agent posts. per_file bounds the highest-density file; per_review bounds the whole PR. Both default to a level that reads as “thorough but not noisy” — drop them for stricter repos where every line should earn a comment.

languages

Default: . A map keyed by language id (typescript, python, go, rust, …). Each value carries the same keys as the top level and overrides them only for files written in that language. See the language examples below.

Annotated full example

A complete review.yml with every key exercised. The inline # comments call out non-obvious fields — strip them before committing if you'd rather keep the file terse.

# Schema pin — always 1 today. Bumping this is a breaking change.
version: 1

# How deep the review goes. One of summary | standard | deep.
depth: standard

# Glob allowlist; only files mathing at least one entry are reviewed.
paths:
  - "src/**"
  - "packages/*/src/**"
  - "scripts/**"

# Carve a hole in the allowlist — test files get a separate pass.
paths:
  ignore:
    - "**/*.test.ts"
    - "**/*.spec.tsx"

# Skip these even when paths allows them. Use for generated/vendored files.
ignore:
  - "**/generated/**"
  - "package-lock.json"
  - "yarn.lock"

# Cap inline comment volume so big PRs stay readable.
comments:
  per_file: 5      # max comments on any single file
  per_review: 40   # max comments across the whole PR

# Per-language overrides — keys here mirror the top level.
languages:
  typescript:
    depth: standard
    comments: { per_file: 6, per_review: 50 }
  python:
    depth: deep
    paths:
      - "**/*.py"
  go:
    depth: standard
    comments: { per_file: 4, per_review: 30 }
  rust:
    depth: deep
    comments: { per_file: 7, per_review: 60 }

Language-specific overrides

The languages block lets you re-tune depth, paths, ignore, or comments for one ecosystem without affecting the others. Each snippet below would slot under languages: in the file above.

TypeScript

typescript:
  depth: standard
  paths:
    - "apps/web/src/**"
    - "apps/api/src/**"
  ignore:
    - "**/*.d.ts"
  comments:
    per_file: 6
    per_review: 50

Python

python:
  depth: deep
  paths:
    - "**/*.py"
  ignore:
    - "**/migrations/**"
    - "**/__pycache__/**"
  comments:
    per_file: 7
    per_review: 60

Go

go:
  depth: standard
  paths:
    - "**/*.go"
  ignore:
    - "**/vendor/**"
    - "**/*_generated.go"
  comments:
    per_file: 4
    per_review: 30

Rust

rust:
  depth: deep
  paths:
    - "src/**/*.rs"
    - "crates/*/src/**/*.rs"
  ignore:
    - "**/target/**"
  comments:
    per_file: 7
    per_review: 60

Minimum viable config

Want VeriFlow to just work without any opinions baked in? Commit a file containing nothing but the schema pin — every other key falls back to its default.

version: 1

Drop this snippet into .github/review.yml on the default branch of the repo you want VeriFlow to start reviewing — the next pull request will pick it up automatically.