> ## Documentation Index > Fetch the complete documentation index at: https://docs.builddown.ai/llms.txt > Use this file to discover all available pages before exploring further. # External code reviewers > The review-findings contract an external reviewer posts, who AI-Implement reads it from, how it waits for the review check, and which findings gate the merge. > [!WARNING] > > **Experimental version.** > > This is the latest in-development version of AI-Implement. Features may change without notice and behavior is not guaranteed. Switch to the [latest stable version here](https://docs.builddown.ai/introduction.md). You can run your own code reviewer next to AI-Implement's built-in reviewers. A reviewer such as Codex posts its verdict on the pull request. AI-Implement reads that verdict and folds the findings into its own review. The reviewer states its verdict in a fixed format. This page describes that format, who can post it, and how AI-Implement waits for it. ## The findings block The reviewer ends its pull-request comment with one fenced code block. The info string is exactly `json review-findings`. The JSON stays on one line. ```` ```json review-findings {"schema":"review-findings/v1","verdict":"changes_requested","findings":[{"severity":"blocking","path":"src/x.ts","line":42,"body":"..."}]} ``` ```` The block carries these fields: | Field | Required | Values | | - | - | - | | `schema` | yes | exactly `review-findings/v1`; any other value is rejected | | `verdict` | yes | `approve`, `changes_requested`, `incomplete` | | `findings` | yes | array; empty when nothing is found | | `findings[].severity` | yes | `blocking`, `minor` | | `findings[].body` | yes | self-contained description | | `findings[].path` | no | file path | | `findings[].line` | no | one-based line | AI-Implement parses the block by these rules: * A broken or unclosed block makes the verdict `incomplete`. AI-Implement does not fall back to the comment prose. * With more than one block in one comment, the last block counts. * Every finding in the block gates the merge, including a `minor` one. When AI-Implement cannot parse the block, the pull-request comment shows this line: ``` ⚠️ External review findings could not be parsed — verdict from reviewer summary only. ``` ## Who can post the block AI-Implement reads the block only from a trusted comment author. Two kinds of author are trusted: * `github-actions[bot]` — a workflow that posts with its `GITHUB_TOKEN`. * One of these logins: `ai-implement`, `ai-implement[bot]`, `claude`, `claude[bot]`, `claude-code[bot]`. A trusted author can approve a pull request. > [!WARNING] > > A reviewer that posts as its own GitHub App or user is not read. To trust that login, add it to [Trusted Review Authors](https://docs.builddown.ai/latest/configuration/team-repo-mappings.md#param-trusted-review-authors). ## When AI-Implement reads the block The post-push review reads the newest eligible comment while the run waits for the review check. A review posted after the run ends still counts. A finding from a trusted author queues a review-fix run. ## The review check AI-Implement waits for a check run whose name matches. It recognizes these names by default: * `review` * `code-review-plugin` * `claude-review` * `claude code review` * `claude-code-review` * any name that contains both `claude` and `review` Set `reviewCheckNames` in `.ai-implement/config.yml` to replace the defaults with exact matches — see [`reviewCheckNames`](https://docs.builddown.ai/latest/customize/custom-steps#param-review-check-names). AI-Implement waits up to five minutes for the check to finish. What it does depends on the check state: | Check state | Result | | - | - | | Finishes with `success`, `failure`, or `stale` | AI-Implement reads the verdict and findings | | Any other conclusion (skipped, neutral, cancelled, timed out) | Fails closed: no auto-approval | | Still running after 5 minutes | Fails closed: "external review did not complete" | | No matching check on two probes in a row | Fails open: review continues without it, with a warning | | Check runs cannot be read (permission) | Run stops with `CHECKS_PERMISSION_DENIED` (see [GitHub App setup](https://docs.builddown.ai/latest/setup/github-app.md)) | ## Review process Each project sets a **Review process**. It selects who reviews a pull request and how AI-Implement reads the verdict. The Review process has these values: * **AI-Implement** — the default. AI-Implement's own reviewers review the pull request. * **Claude Code Review** — Claude Code Review reviews the pull request. AI-Implement fixes Claude's findings. * **Claude Code Review, repository auto-fix** — Claude Code Review reviews the pull request. The repository's own auto-fix workflow fixes Claude's findings, and AI-Implement does not. See [Repository auto-fix](#repository-auto-fix). An unknown or empty value means **AI-Implement**. ### Claude Code Review verdict Under both Claude Code Review processes, AI-Implement reads the verdict from the strongest source it finds. It trusts `claude[bot]` and `claude`. AI-Implement matches a review check by its name and the app that posts it. A same-named check from another app does not count. It reads these sources in order: 1. A `json review-findings` block from a trusted author. See [The findings block](#the-findings-block). 2. The hosted Claude Code Review check. This check is named `Claude Code Review` and comes from the `claude` app. AI-Implement reads its severity line. A normal finding requests changes. No normal finding approves the pull request. 3. The repository's own Claude workflow. This review check comes from `github-actions`, with a name from the project's review check names. AI-Implement also reads Claude's inline comments on the pull-request head. A failed check is not a verdict. In source 3, AI-Implement reads the marker at the start of each inline comment: * 🔴 — blocking. * 🟡 — minor. * 🟣 — ignored. * No marker — minor. A comment on a resolved or outdated review thread does not count. AI-Implement also reads the section headings in Claude's summary comment. A heading that starts with 🔴 is blocking. It stops approval even when the review check passes and Claude posts no inline comment. A heading that starts with 🟡 is minor. ## Repository auto-fix Use **Claude Code Review, repository auto-fix** when the repository runs its own workflow that fixes Claude's review comments. Under **Claude Code Review**, AI-Implement and that workflow can both push fixes to one pull request, and each push starts another review. This process reads Claude's verdict the same way as **Claude Code Review**. It changes who fixes. When Claude's review of the newest commit is done, AI-Implement does this: | AI-Implement's review | Claude's review | What AI-Implement does | | - | - | - | | Passes | Blocking finding | Starts no fix. Waits for the repository's auto-fix | | Blocking finding | Passes | Pushes a fix, the same as under the other processes | | Blocking finding | Blocking finding | Starts no fix. Asks for a person | | Passes | Passes | Approves | When AI-Implement waits for the auto-fix, it posts: ``` ⏳ Internal review passed. Claude's review found blocking issues; waiting for the repository's auto-fix. No AI-Implement fix pass will run. ``` AI-Implement then checks the pull request once a minute for up to 30 minutes. It follows each commit that the auto-fix pushes. It approves the newest commit only when all of these hold: * Claude's review check on that commit finished with `success`. A skipped review check is not a review. * The other checks on that commit passed. * Claude reported no 🔴 finding on that commit. A commit that still has a 🔴 finding keeps AI-Implement waiting, because the auto-fix can push again. If no commit passes in 30 minutes, AI-Implement does not approve, and a person reviews the pull request. Closing the pull request ends the wait. AI-Implement never starts a fix run for Claude's findings on this process, after the run or during it, on either lifecycle. > [!WARNING] > > If the repository's review workflow skips commits pushed by a bot, the auto-fix commit gets no review. AI-Implement then does not approve it, and the pull request waits for a person. To use this process, follow [Switch a project to Claude Code Review](#switch-a-project-to-claude-code-review), and select **Claude Code Review, repository auto-fix** in the Review process step. ## Switch a project to Claude Code Review Switch a project to Claude Code Review when you want Claude to review its pull requests instead of AI-Implement's built-in reviewers. Test the change on one pull request before you rely on it. **1. Switch the project to the Restate lifecycle** A review that posts findings after the run hands them to the Restate fix coordinator. A Restate workflow then owns the fix run with a deadline, so the fix survives an orchestrator restart. Claude Code Review was built and tested on this path. Open the project drawer in the project settings. Set **Review-fix & Planning Lifecycle** to **Restate (pilot)**, then save. The save is refused unless all of these hold: * The execution mode is GitHub Actions. * The Restate endpoint is healthy and registered. * The project's workflow file is current. * No run started by an older orchestrator version is still in flight. To bring the workflow file up to date, use **Sync workflows** and merge the pull request it opens. Claude Code Review also works on the Legacy lifecycle, but these steps assume Restate. See [`reviewFixLifecycle`](https://docs.builddown.ai/latest/configuration/team-repo-mappings#param-review-fix-lifecycle). **2. Check the prerequisites** Confirm these before you switch: * The project settings show a **Review process** select. If they do not, update AI-Implement. * The runner image is built from `testing` on or after 2026-10-11. An earlier image does not post the approval message for a review that passes after the run ends. * The repository runs a Claude review workflow that: * runs on the pull request as a GitHub Actions job, so its check run comes from `github-actions` * posts inline comments as `claude[bot]`, which needs the Claude GitHub App * uses a check name AI-Implement recognizes — a default review check name, or one you set in [`reviewCheckNames`](https://docs.builddown.ai/latest/customize/custom-steps#param-review-check-names) * Alternatively, the repository posts the hosted Claude Code Review check. See [Claude Code Review verdict](#claude-code-review-verdict). **3. Set the Review process to Claude Code Review** Open the project drawer in the project settings. Set **Review process** to **Claude Code Review**, then save. Under Claude Code Review, an empty internal-reviewer selection does not stop the run. **4. Add Trusted Review Authors (optional)** Add extra comment authors in [Trusted Review Authors](https://docs.builddown.ai/latest/configuration/team-repo-mappings.md#param-trusted-review-authors). Add an author here when a workflow posts its verdict as a login other than `claude[bot]` or `claude`. > [!WARNING] > > Only `claude[bot]` and `claude` inline comments count toward the verdict. Trusted Review Authors does not change this. It adds authors whose [`json review-findings` block](#the-findings-block) counts, not authors whose inline comments count. A workflow that posts as `github-actions[bot]` must post a findings block, or AI-Implement does not read its inline comments. **5. Test on one pull request** Add the pickup label to one small issue. AI-Implement opens a pull request and runs the review. Watch the pull request for the review result. AI-Implement posts one of these comments. The review passed in time: ``` ✅ Approved (N iteration…) ``` Let the pull request merge. A 🔴 comment blocked the review: ``` ⚠️ Reviewer found issues — starting fix pass … ``` AI-Implement pushes a fix, then reviews again. Wait for the next result. Claude took longer than the run's wait: ``` ⚠️ Internal review passed, but the external review did not complete within the wait budget. Not auto-approving. ``` AI-Implement then rechecks the pull request once a minute for up to 30 minutes. When the review passes on the same commit with no open blocking finding, it posts: ``` The external review passed on `` after the run ended, with no open blocking finding. The run's approval mark is written, so auto-merge can proceed. ``` Wait for this message, then let the pull request merge. **6. Switch back, if needed** To return to AI-Implement's own reviewers, set **Review process** to **AI-Implement** in the project settings, then save. This does not change the lifecycle. The project stays on the lifecycle you selected. ## Which findings gate the merge Merge gating depends on where a finding comes from: | Source | Gates the merge | | - | - | | The findings block | yes | | A GitHub review with "Request changes" | yes | | An inline review thread | only when that reviewer's latest review requests changes | | AI-Implement's internal reviewers | per the reviewer's **Gates** checkbox in the project settings | | A 🔴 heading in Claude's summary comment, under both Claude Code Review processes | yes | | Other prose findings in a comment with no block | advisory only | AI-Implement splits the two kinds in the pull-request comment. Gating findings go under "Unresolved external review findings:". Advisory findings go under "Advisory external review findings (do not block merge):". ## Build your own reviewer A reviewer has two obligations: * Post the comment from a workflow step, not from the model's own comment tool. * Fail the check when there is no valid verdict. Never post a partial or synthetic block. A non-Claude reviewer follows this outline: **1. Produce the verdict JSON** Build the `{"schema":"review-findings/v1","verdict":...,"findings":[...]}` object as one line of valid JSON. An empty result is still a `findings: []` block, not a missing one. **2. Render the comment** Write the human-readable body, then append the fenced block with the info string `json review-findings`. **3. Post the comment** Post it with `gh pr comment` from the workflow step. The AI-Implement repository is public at `BuildDownAI/AI-Implement`. It ships a reusable composite action at `.github/actions/claude-review` that does this for Claude. The action takes these inputs: * `github_token` and `pr_number` — required. * One of `claude_code_oauth_token`, `anthropic_api_key`, `use_bedrock`, or `use_vertex`. * `prompt_extra` — optional. AI-Implement does not sync this action to target repositories. Copy or reference it yourself. ## Turn off the wait Set `reviewProviders: []` in `.ai-implement/config.yml` to skip the wait — see [`reviewProviders`](https://docs.builddown.ai/latest/customize/custom-steps#param-review-providers). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.