opencode-review-protocol — Claude Code prompt for PR reviews
The opencode-review-protocol Claude Code prompt defines a pull request review workflow. It posts line-specific findings, updates a summary comment, and writes a verdict for CI.
Apache-2.0 ★ 423 updated 2026-11-16
.claude/commands/opencode-review-protocol.mdWhat opencode-review-protocol does
The prompt tells an agent to post one inline comment for each finding, then update the pull request summary and write pass or fail to ./.opencode-verdict.txt. Any Critical, High, or Medium finding produces fail; Low findings alone, or no findings, produce pass.
A workflow appends this shared protocol to a header for the review type. The agent uses gh to post GitHub comments and stages the summary in ./.opencode-summary.md, deleting that file after posting. If a summary from an earlier push exists, it edits that comment instead of creating another.
The workflow needs gh, the GITHUB_REPOSITORY, PR_NUMBER, and HEAD_SHA variables, plus an available skill to analyse the changes. It must not modify repository files or fetch external URLs. The only persistent file it may write is ./.opencode-verdict.txt.
What it helps with
- attach a review finding to its exact changed line
- collect inline findings in one pull request summary
- write a pass or fail verdict for CI
- update an earlier summary instead of duplicating it
- stop the review when its skill is unavailable
Example prompts for the agent
- Review this pull request and comment on each issue at the relevant line.
- Run the review protocol on these changes and update the summary comment.
- If the review skill fails, write
failas the verdict.
How to install opencode-review-protocol
Manually: put the files in place
.claude/commands/opencode-review-protocol.mdHow to use
Paste the text at the start of a chat or into project instructions
Questions about opencode-review-protocol
How do I install opencode-review-protocol in Claude Code?
Save the prompt file at .claude/commands/opencode-review-protocol.md.
What does opencode-review-protocol do?
It defines a pull request review workflow with inline findings, a summary comment, and a pass or fail verdict.
What does opencode-review-protocol need to run?
It needs gh, the GITHUB_REPOSITORY, PR_NUMBER, and HEAD_SHA variables, and an available skill to analyse the changes.
Source text
opencode-review-protocol.md · Apache-2.0
<!-- Shared review protocol. This file is never sent to the model on its
own: .github/workflows/opencode-review-reusable.yml appends it after a
per-kind header (.github/prompts/opencode-review-<kind>.md). Placeholder
tokens in angle brackets — <KIND>, <KIND_HYPHEN>, <SKILL_ID>,
<SKILL_PATH>, <FINDING_DESC>, <SEVERITY_NOTE>, <INLINE_SCOPE_LIMIT>,
<SUMMARY_HEADING>, <NO_FALLBACK> — are defined in that header's
"Protocol parameters" section; substitute them everywhere below. -->
## Step 3 — Translate skill output into inline comments
For each <FINDING_DESC> the skill surfaces, post one inline review comment on the exact line:
```
gh api repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/comments \
-F commit_id="${HEAD_SHA}" \
-f path=<file> \
-F line=<n> \
-F side=RIGHT \
-f body=<body>
```
Inline comment body format:
```
**[Severity] Category:** one-line description of the issue.
Why this matters: <one sentence>.
Suggested fix: <one sentence or a 2–3 line code snippet>.
```
<SEVERITY_NOTE> One finding per inline comment. If the same issue appears on multiple lines, pick the clearest occurrence and reference the others in its body. <INLINE_SCOPE_LIMIT>
## Step 4 — Write the verdict
After posting inline comments and before composing the summary, write the verdict to `./.opencode-verdict.txt` in the workspace root:
- `fail` if any posted finding has severity `Critical`, `High`, or `Medium`.
- `pass` if posted findings are only `Low`, or none.
Single word, no other content. This file is the ONLY persistent file you may write.
## Step 5 — Compose and post the summary
Compose the top-level summary body with this shape:
```
<SUMMARY_HEADING>
<one short paragraph summarising what the skill analysed and the overall posture>
<bulleted list of inline findings by severity, or "No issues found.">
**<KIND>:** ✅ no issues found
<!-- opencode-verdict: pass -->
```
The final two lines are the load-bearing verdict signal:
- A marker line starting `**<KIND>:** ...` — use `✅ no issues found` when you posted zero `Critical`/`High`/`Medium` findings, or `⚠️ N issue(s) flagged inline` (exact count) otherwise.
- Immediately after it, the machine-readable HTML comment `<!-- opencode-verdict: pass -->` or `<!-- opencode-verdict: fail -->`. It renders invisibly on GitHub; CI reads it as the authoritative verdict. The marker value must match the verdict file.
### Posting the summary
Use the discover-then-edit pattern so the PR ends up with exactly one <KIND_HYPHEN> summary comment, not one per push:
1. Look up any prior summary written by this workflow:
```
gh api "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" \
--jq 'map(select(.user.login == "github-actions[bot]"
and (.body | contains("**<KIND>:**"))))
| sort_by(.created_at)
| last
| .id // empty'
```
2. If that returns a numeric id, **edit** the existing comment in place:
```
gh api -X PATCH "repos/${GITHUB_REPOSITORY}/issues/comments/<id>" -f body="$(cat ./.opencode-summary.md)"
```
3. Otherwise, **create** a fresh comment:
```
gh pr comment ${PR_NUMBER} --body-file ./.opencode-summary.md
```
Stage the summary body in a workspace-local temp file `./.opencode-summary.md` so it survives shell quoting, and **delete that temp file after posting**. Never post a second summary in the same run — if PATCH fails, surface the error rather than falling back to `gh pr comment`.
The posted body must be the file's **content** — `$(cat ./.opencode-summary.md)` or `--body-file` — never a file reference. An `@@/.opencode-summary.md` mention, a bare path, or any other reference syntax is posted as literal text and the PR gets a placeholder instead of its summary and verdict marker (observed on PR #337). Before finishing, re-read the posted comment's body and confirm it starts with the `**<KIND>:**` header line; if it does not, surface the error and stop — do not leave a placeholder.
## Step 6 — Failure mode: skill unavailable or errors mid-run
If the `<SKILL_ID>` skill cannot be invoked or errors out mid-run — examples: the `skill` tool reports it is not installed, `<SKILL_PATH>` cannot be located, or the skill exits with an error you cannot work around — do the following and stop:
1. Write `fail` to `./.opencode-verdict.txt`.
2. Post-or-update the summary comment (using the discover-then-edit pattern above) naming the failure, e.g. `**<KIND>:** ⚠️ <SKILL_ID> skill unavailable or failed. Details: <short description of what failed>.` followed by `<!-- opencode-verdict: fail -->`.
3. Do **NOT** fall back to <NO_FALLBACK>. The review must be loudly broken, not silently degraded to ad-hoc heuristics.
## Constraints
- Do not modify any files in the repo. The only persistent file you may write is `./.opencode-verdict.txt`; the summary body may be staged in `./.opencode-summary.md` and must be deleted after posting.
- Stage every scratch file — a patch dump, a fetched fragment, anything you write in order to read it back — under the workspace root (for example `./.review-scratch.txt`), never under `/tmp` or any path outside the repository: the sandbox auto-rejects reads of external directories, which kills the review mid-run (observed twice on PR #761, `external_directory (/tmp/*)` auto-reject). Delete the scratch file when you are done with it.
- Do not fetch external URLs. Shell use is limited to the `gh pr ...` and `gh api repos/...` invocations described above and the verdict/summary file handling.
- Keep inline comments short and high-signal. If you are unsure whether something is a real issue, prefer not posting — false positives erode trust in this check faster than missed findings.
© relatedb · Apache-2.0 · relatedb/relate