werkator/docs/prs/2026-10-06-PR#127-agents-pr-workflow-with-ai-review.md

WARNING: This document describes only the change applied in this PR. It may already be outdated once the next PR is merged. Historic PR-documentation is not maintained along with new PRs — treat it as a snapshot, not as current documentation.

The Problem

Since 2026-10-06 the branch protection of main requires the status ai-review/gate and one approval, from the review bot ai-reviewer or from mi. werkrevisor reviews every pull request without the WIP: title prefix, and its bot ai-reviewer approves only a GREEN one. The bot never approves a pull request that it opened itself, so agents use the separate account claude-code.

Agents in other sessions do not know this workflow yet. A pull request opened without WIP: would get no review at all, since werkrevisor reviews only a pull request whose title changed from WIP: to one without.

Non-Goals

• No change of Werkator's behaviour: the review runs as a host-pinned pull-request target build, configured on the host.
• No .werkrevisor.toml: the host config of werkrevisor holds Werkator's review rules for now.

The Scenarios

Feature: agents follow the review workflow

Background

• Agents push and open pull requests as the Gitea account claude-code.
• The review bot is the separate account ai-reviewer; it approves only pull requests that other accounts opened.

Scenario#127.01: an agent opens a pull request as work in progress

So that no review starts on unfinished work.

• Given an agent has pushed a branch with a change
• When the agent opens the pull request
• Then the title starts with WIP:

Verified by

• no automated test: a process rule for agents, stated in AGENTS.md; this pull request was opened as "WIP: Agents open pull requests …" by claude-code

Scenario#127.02: removing the WIP prefix starts the review, and the review leads to the merge

So that a finished pull request merges without a click once it is GREEN, or once mi approves it after YELLOW or ORANGE.

• Given a pull request with the title prefix WIP: is ready for review
• When the agent removes the prefix from the title
• Then the pull request shows the result of a werkrevisor review
  • and the pull request has a scheduled merge, unless the result is RED or ERROR

Verified by

• test_flow.ReadinessAndAutomergeTest in werkrevisor

The Solution

• AGENTS.md gets the section "Pull Requests and AI Review" with the workflow and the rule to fix the review's findings.
• The template docs/prs/TEAMPLATE.md and the pr-doc skill describe open questions as checkbox items, see below.
• The version is 1.37.8 with a release-notes entry, as for every pull request.

Additional Changes

• The template docs/prs/TEAMPLATE.md (its file name has kept this spelling) and the pr-doc skill take over the format of open questions from hsadmin-ng: the section is optional, - [ ] TODO.<topic>: defers a point, any other unchecked item blocks the merge. Before, open questions were plain bullets, which the AI review could not tell from blocking questions.

Prerequisite PRs

• werkrevisor PR#18: the review of Werkator, the WIP transition as the start of the review and the merge by the bot.