> For the complete documentation index, see [llms.txt](https://docs.tessl.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tessl.io/tutorials/setting-up-agentic-code-review.md).

# Setting up agentic code review

{% hint style="info" %}
**Takeaways:** After reading this page you will understand how the `tessl change` command group works, how to use the `tessl agent` to create a code review skill for your repository, how to set up a policy-based risk gate that decides when PRs need a human reviewer, and how to wire verifiers as CI checks that enforce code invariants.
{% endhint %}

Agents write code faster than human reviewers can keep up with. The tools described here handle three distinct problems: catching obvious issues before human reviewers see them, deciding which PRs actually need human review, and enforcing structural invariants automatically.

Throughout this tutorial the `tessl agent` does the heavy lifting. It ships with the `tessl/harness-engineering` plugin pre-bundled, so the skills that drive code-review setup — `change-review`, `change-risk`, `change-verify`, and `plugin-creator` — are available without installing anything. You describe what you want; the agent runs the underlying `tessl change` commands and shows you what it ran.

{% hint style="info" %}
Prefer your own coding agent? Install the plugin into it with `tessl install tessl/harness-engineering` and the same skills become available there. The rest of this tutorial assumes the `tessl agent` as the base case.
{% endhint %}

## How the tessl change command group works

`tessl change` groups three commands, each covering a separate concern:

* `tessl change review` — runs a readonly agent against the current diff using the skills you specify, and emits a structured review (summary and inline comments keyed to GitHub hunk positions). The command never posts to GitHub; a separate publisher step does that.
* `tessl change risk` — scores the current diff against a checked-in policy and outputs a gate decision: does this PR require human review? The agent's risk judgment is advisory; the policy decides whether the PR is clearly low-risk enough to skip review, and requires a human whenever it is uncertain.
* `tessl change verify` — runs verifiers against changed files. Verifiers are LLM-as-judge checks for targeted, observable invariants — things a linter cannot express but a reviewer can score by reading the file. They run like linting checks in CI, and you can generate them from skills already in your repo (see [Step 5](#step-5-author-and-deploy-verifiers)).

Each command can be tried locally before you automate anything.

## Concepts

**Skills** are the unit of code review knowledge. A skill contains instructions that guide the agent's analysis of a diff. Any skill in your repo can act as a review lens — not only ones explicitly built for review — and one call to `tessl change review` can run several skills in parallel and interlace their findings into one review.

**Risk policy** is a set of checked-in files under `.github/pr-review-gate/` that define what makes a PR low-risk enough to skip human review. The agent's risk judgment is advisory; the policy decides the gate, and when in doubt it requires a human reviewer.

**Verifiers** are checks that describe binary, observable invariants about committed files — things like "API response handlers must use typed helpers" — that are hard to express as a lint rule but judgeable from the file. A verifier targets a glob of files, so new files added later are covered too. They are the right tool when a reviewer keeps flagging the same structural pattern and no deterministic check can own it.

## Prerequisites

* Tessl installed and initialized (`tessl init`)
* Authenticated (`tessl login`)
* Access to a workspace

## Step 1: Try a code review locally

Before setting up automation, run a review on the current diff to see what output looks like.

The `tessl agent` already bundles the `tessl/code-review` skills, which provide several focused review lenses. Ask the agent to run a review:

> Run a code review on my current diff using the code-legibility lens.

Under the hood the agent runs:

```sh
tessl change review --skill tessl/code-review#review-code-legibility
```

The `--skill` flag accepts three formats:

* Registry ref: `workspace/plugin[@version]#skill-name` — the `#skill-name` selector is optional when the plugin has exactly one skill
* Local path: a path to a `SKILL.md` file or skill directory in this repo
* Installed skill name: a bare name resolved against installed skills

To run multiple lenses in one call, repeat `--skill`. The CLI executes them in parallel and interlaces their findings into one structured output:

```sh
tessl change review \
  --skill tessl/code-review#review-code-legibility \
  --skill tessl/code-review#review-test-risk
```

Available skills in `tessl/code-review`:

| Skill                        | Use when the most important signal is                                                  |
| ---------------------------- | -------------------------------------------------------------------------------------- |
| `review-code-legibility`     | Whether names, types, return shapes, and abstractions are clear from the code alone    |
| `review-test-risk`           | Changed behaviour without meaningful tests, or brittle/uncovered async and error paths |
| `review-contract-boundaries` | API schemas, generated clients, CLI flags, event payloads, database migrations         |
| `review-security-risks`      | Auth, untrusted input, injection, secrets, crypto, sensitive logging                   |
| `review-local-precedent`     | Whether new code should have reused an existing helper, component, or convention       |

To compare against a specific base commit, pass `--base origin/main`. To capture the structured data, add `--json --output review.json`.

## Step 2: Create your own code review skill

The published skills are a starting point. Once you know what signals matter for your codebase, create a focused skill that captures project-specific patterns.

Ask the `tessl agent` to build it. The agent uses its `plugin-creator` skill to scaffold the plugin, interview you about scope, and validate the result:

> Create a code review skill for this repo that flags breaking changes to our API schemas, generated clients, and route contracts. Put it in a plugin under the engteam workspace.

As it works, the agent runs the underlying CLI commands and reports them back. The ones you will see most often:

* `tessl plugin new` — scaffolds the plugin and skill directory ([reference](/reference/cli-commands.md#tessl-plugin-new))
* `tessl plugin lint` — checks packaging and schema ([reference](/reference/cli-commands.md#tessl-plugin-lint))
* `tessl review` — reviews the SKILL.md quality and can gate CI ([reference](/reference/cli-commands.md#tessl-review))
* `tessl plugin publish` — publishes to the registry when the skill is stable ([reference](/reference/cli-commands.md#tessl-plugin-publish))

To iterate, ask the agent to run the skill against the current diff and tune the `SKILL.md` based on what the review misses or gets wrong:

> Run my new review skill on the current diff, then sharpen the instructions for anything it flagged incorrectly.

Old PRs make good test cases. The `tessl agent` can check out or reconstruct a past PR's diff, run the skill against it, and compare the findings to what reviewers actually cared about — repeating until the skill is stable:

> Backtest this review skill against PRs #1189 and #1201 and tell me where its findings differ from the human review comments.

## Step 3: Wire the review into every PR

The `tessl change review` command emits structured review data only — it never posts to GitHub. To run it on every PR you need a GitHub Actions workflow that runs the command plus a publisher step that posts the single review with inline comments.

Rather than copy a fixed workflow file, ask the `tessl agent` to set it up. It reads how your repo is configured and calibrates the workflow accordingly:

> Set up a code review for every new PR.

The agent (via its `change-review` skill) chooses sensible defaults. The ones worth knowing — and how you might change them:

* **One reviewer lens to start** — it wires a single `--skill`, because trust builds faster with one focused lens. Add more `--skill` values to the same run once you trust the output.
* **An explicit base ref** — a detached PR checkout often has no `origin/main` tracking ref, so the workflow fetches it and passes `--base`. Without this the default base is unresolvable and the run fails.
* **A gated manual re-run trigger** — an `@tessl-change-review` PR comment, restricted to repository insiders (owner, member, collaborator, admin) so external contributors cannot start a secret-backed run. Drop it if you only want automatic runs.
* **One automatic review per PR** — a starting cadence, not a rule. Move to every-push only when the added cost and noise are worth it.

Set `TESSL_TOKEN` (and `ANTHROPIC_API_KEY`) as repository secrets; `GITHUB_TOKEN` is provided automatically.

## Step 4: Set up the risk gate

The risk gate decides whether a PR requires human review based on a checked-in policy, combining git measurements with an advisory agent judgment.

Ask the `tessl agent` to set it up — it uses its `change-risk` skill to initialize the policy, design it with you, and trial it before you rely on it:

> Set up a PR risk gate for this repo.

The agent runs `tessl change risk init`, which writes starter files under `.github/pr-review-gate/`. Two starters are available:

* `conservative-starter` (default) — requires human review for most changes; gradually relax as you verify the gate behavior
* `official-review-policy-parity` — matches your existing branch protection rules more closely

Read and edit the policy files before relying on the gate. To score the current diff against the policy, the agent runs `tessl change risk` (add `--base origin/main` to compare against a base, `--json` for CI-friendly output). In CI, `--fail-if-review-required` exits non-zero when the gate decides a human reviewer is needed:

```sh
tessl change risk --base origin/main --fail-if-review-required --json
```

Add this to GitHub Actions as an advisory status check first. Watch it on real PRs for a few weeks before making it required. When the signal is trusted, enable it as a required status check in branch protection settings.

## Step 5: Author and deploy verifiers

Verifiers check binary, observable invariants about committed files. Use them when a reviewer keeps flagging the same structural pattern and no linter can own it. Drive the whole flow through the `tessl agent`, which uses its `change-verify` skill.

**Create a first verifier.** Ask the agent for one targeted check:

> Create a verifier that checks every Fastify route file returns via our typed response helpers.

The agent authors the verifier JSON and wires it into the `verify` block in `tessl.json` (see the [`verify` block reference](/reference/configuration.md#verify-block) for the full schema). Before any broad judge run it previews the scope — `tessl change verify lint <file>` to check the structure, then `tessl change verify --dry-run --all --show-files` to confirm which files match.

**Run that first verifier.** Have the agent run just the new check on changed files and sample a few outputs so you can confirm the failures are real violations:

```sh
tessl change verify --sample 5
```

**Generate more, then run them all.** Once the first verifier earns trust, ask the agent to propose additional ones — often mined from your reviewer skills or recurring review feedback — and run the full set:

> Suggest a few more verifiers from the patterns my reviewers keep flagging, then run them all on the current diff.

**Put them into PR review.** Finally, ask the agent to add verification as a CI gate:

> Run verifiers on every PR.

The agent fetches the base ref and runs `tessl change verify --base origin/main --github`. The `--github` flag emits GitHub Actions annotations for warn-level findings so they appear in the PR UI even when the run exits 0. Start with verifiers set to `warn` severity in `tessl.json` while calibrating; promote to `error` (which makes the check blocking) only after you have confirmed the verifier avoids false positives on real PRs.

## Next steps

* Mine your PR review history for recurring patterns and turn them into new verifier rules or reviewer skill improvements with the [Improving agent code quality](/tutorials/improving-agent-code-quality.md) tutorial.
* Improve the quality of your reviewer skills with the `tessl/skill-optimizer` plugin (pre-bundled with the `tessl agent`): ask the agent to review a SKILL.md, generate eval scenarios, run evals, and re-run until scores improve. See [Improving your skills](/improving-your-skills/overview-improving-skills-and-plugins.md) for the underlying review and eval capabilities.
* Once a verifier is validated, publish it alongside your reviewer skills as a single plugin so the whole review setup can be distributed across repositories.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.tessl.io/tutorials/setting-up-agentic-code-review.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.