Skip to main content
prompt CX Codex GP ChatGPT

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/opencode-review-protocol.md
Open on GitHub

What 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 fail as the verdict.

How to install opencode-review-protocol

Manually: put the files in place

.claude/commands/opencode-review-protocol.md

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

Similar prompts

All prompts for Code review and refactoring →

From the same set18

The whole set →
stellar-nightshift The stellar-nightshift prompt for Claude Code applies the remedy for each finding in a supplied cluster and leaves unrelated code alone. It targets files in the cluster’s crate directories. CX Codex +1 ★ 423repo stars opencode-review-rust The opencode-review-rust Claude Code prompt automates Rust pull request reviews. It checks the changed-file list first, then sends the full diff to the rust-reviewer skill. CX Codex +1 ★ 423repo stars opencode-review-security The opencode-review-security Claude Code prompt reviews Rust pull requests for security risks. Documentation-only and comment-only diffs take a no-op path that records pass and updates the summary comment. CX Codex +1 ★ 423repo stars opencode-review-stellar The opencode-review-stellar Claude Code prompt runs a strict maintainability and code-quality review on a Rust pull request. It gathers agent findings but leaves comments and the final verdict to a later pipeline step. CX Codex +1 ★ 423repo stars release-notes A prompt for Claude Code drafts relate release notes from the changelog and commit history. It runs for a tagged release. CX Codex +1 ★ 423repo stars security-review The security-review Claude Code skill reviews code changes for security risks and suggests remediations. It activates for auth or permission changes, secrets and PII handling, public endpoints, and dependency upgrades. CX Codex +1 ★ 423repo stars neo4j-query-workload-skill The neo4j-query-workload-skill Claude Code skill builds a graph-database query workload one requirement at a time. It runs new queries against the dataset and checks earlier results for regressions. CX Codex +1 ★ 423repo stars relate This Claude Code skill guides JVM projects through using Relate as a local graph database with Cypher. It activates when Java or Kotlin code needs to create, query, or embed the database. CX Codex +1 ★ 423repo stars

Project sponsors

Companies that keep this analytics open