From e8cf122863622ef2322f7140d7ac1b4540dc56e2 Mon Sep 17 00:00:00 2001 From: bokobza Date: Thu, 10 Sep 2026 13:39:48 +0100 Subject: [PATCH 1/3] feat: reusable Claude PR review workflow and shared review skill Adds .github/workflows/claude-review.yml, a workflow_call workflow that repos call from a 10-line claude-review.yml to get Claude reviews on every pull request, and .claude/skills/code-review/SKILL.md, the multi-agent review skill it runs. The workflow checks out this repo and copies the skill into the reviewed repo at run time, so each repo's own CLAUDE.md files drive the compliance checks. Findings post as inline comments on the diff; a summary comment is updated in place when nothing is found. Drafts are reviewed, every push is re-reviewed, and a new push queues behind a running review instead of cancelling it. Authenticates with the org CLAUDE_CODE_OAUTH_TOKEN, so reviews bill the Claude subscription. Co-Authored-By: Claude Opus 5 --- .claude/skills/code-review/SKILL.md | 110 ++++++++++++++++++++++++++++ .github/workflows/claude-review.yml | 69 +++++++++++++++++ README.md | 16 ++++ 3 files changed, 195 insertions(+) create mode 100644 .claude/skills/code-review/SKILL.md create mode 100644 .github/workflows/claude-review.yml diff --git a/.claude/skills/code-review/SKILL.md b/.claude/skills/code-review/SKILL.md new file mode 100644 index 0000000..7fd9fd1 --- /dev/null +++ b/.claude/skills/code-review/SKILL.md @@ -0,0 +1,110 @@ +--- +name: code-review +allowed-tools: Bash(gh issue view:*), Bash(gh search:*), Bash(gh issue list:*), Bash(gh pr comment:*), Bash(gh pr diff:*), Bash(gh pr view:*), Bash(gh pr list:*), Bash(gh api:*), mcp__github_inline_comment__create_inline_comment +description: Code review a pull request +--- + +Provide a code review for the given pull request. + +**Agent assumptions (applies to all agents and subagents):** +- All tools are functional and will work without error. Do not test tools or make exploratory calls. Make sure this is clear to every subagent that is launched. +- Only call a tool if it is required to complete the task. Every tool call should have a clear purpose. + +To do this, follow these steps precisely: + +1. Launch a haiku agent to check if any of the following are true: + - The pull request is closed + - The pull request does not need code review (e.g. automated PR, trivial change that is obviously correct) + + If any condition is true, stop and do not proceed. + +Note: Still review Claude generated PRs and draft PRs. This review runs on every push, so a PR that was reviewed earlier is reviewed again for its new head commit. + +2. Launch a haiku agent to return a list of file paths (not their contents) for all relevant CLAUDE.md files including: + - The root CLAUDE.md file, if it exists + - Any CLAUDE.md files in directories containing files modified by the pull request + +3. Launch a sonnet agent to view the pull request and return a summary of the changes + +4. Launch 4 agents in parallel to independently review the changes. Each agent should return the list of issues, where each issue includes a description and the reason it was flagged (e.g. "CLAUDE.md adherence", "bug"). The agents should do the following: + + Agents 1 + 2: CLAUDE.md compliance sonnet agents + Audit changes for CLAUDE.md compliance in parallel. Note: When evaluating CLAUDE.md compliance for a file, you should only consider CLAUDE.md files that share a file path with the file or parents. + + Agent 3: Opus bug agent (parallel subagent with agent 4) + Scan for obvious bugs. Focus only on the diff itself without reading extra context. Flag only significant bugs; ignore nitpicks and likely false positives. Do not flag issues that you cannot validate without looking at context outside of the git diff. + + Agent 4: Opus bug agent (parallel subagent with agent 3) + Look for problems that exist in the introduced code. This could be security issues, incorrect logic, etc. Only look for issues that fall within the changed code. + + **CRITICAL: We only want HIGH SIGNAL issues.** Flag issues where: + - The code will fail to compile or parse (syntax errors, type errors, missing imports, unresolved references) + - The code will definitely produce wrong results regardless of inputs (clear logic errors) + - Clear, unambiguous CLAUDE.md violations where you can quote the exact rule being broken + + Do NOT flag: + - Code style or quality concerns + - Potential issues that depend on specific inputs or state + - Subjective suggestions or improvements + + If you are not certain an issue is real, do not flag it. False positives erode trust and waste reviewer time. + + In addition to the above, each subagent should be told the PR title and description. This will help provide context regarding the author's intent. + +5. For each issue found in the previous step by agents 3 and 4, launch parallel subagents to validate the issue. These subagents should get the PR title and description along with a description of the issue. The agent's job is to review the issue to validate that the stated issue is truly an issue with high confidence. For example, if an issue such as "variable is not defined" was flagged, the subagent's job would be to validate that is actually true in the code. Another example would be CLAUDE.md issues. The agent should validate that the CLAUDE.md rule that was violated is scoped for this file and is actually violated. Use Opus subagents for bugs and logic issues, and sonnet agents for CLAUDE.md violations. + +6. Filter out any issues that were not validated in step 5. This step will give us our list of high signal issues for our review. + +7. Output a summary of the review findings to the terminal: + - If issues were found, list each issue with a brief description. + - If no issues were found, state: "No issues found. Checked for bugs and CLAUDE.md compliance." + + If `--comment` argument was NOT provided, stop here. Do not post any GitHub comments. + + If `--comment` argument IS provided and NO issues were found, post the summary comment and stop. If an earlier run already left a comment starting with `## Code review` on this PR (find it with `gh api repos///issues//comments`), update that comment in place with `gh api --method PATCH repos///issues/comments/ -f body=...` instead of posting a new one. + + If `--comment` argument IS provided and issues were found, continue to step 8. + +8. Create a list of all comments that you plan on leaving. This is only for you to make sure you are comfortable with the comments. Do not post this list anywhere. + + Then fetch the inline comments already on the PR with `gh api repos///pulls//comments` and drop from your list any issue that an earlier run already reported on the same lines. An issue that was fixed since it was reported needs no new comment. + +9. Post inline comments for each issue using `mcp__github_inline_comment__create_inline_comment` with `confirmed: true`. For each comment: + - Provide a brief description of the issue + - For small, self-contained fixes, include a committable suggestion block + - For larger fixes (6+ lines, structural changes, or changes spanning multiple locations), describe the issue and suggested fix without a suggestion block + - Never post a committable suggestion UNLESS committing the suggestion fixes the issue entirely. If follow up steps are required, do not leave a committable suggestion. + + **IMPORTANT: Only post ONE comment per unique issue. Do not post duplicate comments.** + +Use this list when evaluating issues in Steps 4 and 5 (these are false positives, do NOT flag): + +- Pre-existing issues +- Something that appears to be a bug but is actually correct +- Pedantic nitpicks that a senior engineer would not flag +- Issues that a linter will catch (do not run the linter to verify) +- General code quality concerns (e.g., lack of test coverage, general security issues) unless explicitly required in CLAUDE.md +- Issues mentioned in CLAUDE.md but explicitly silenced in the code (e.g., via a lint ignore comment) + +Notes: + +- Use gh CLI to interact with GitHub (e.g., fetch pull requests, create comments). Do not use web fetch. +- Create a todo list before starting. +- You must cite and link each issue in inline comments (e.g., if referring to a CLAUDE.md, include a link to it). +- If no issues are found and `--comment` argument is provided, post a comment with the following format: + +--- + +## Code review + +No issues found. Checked for bugs and CLAUDE.md compliance. + +--- + +- When linking to code in inline comments, follow the following format precisely, otherwise the Markdown preview won't render correctly: https://github.com/anthropics/claude-code/blob/c21d3c10bc8e898b7ac1a2d745bdc9bc4e423afe/package.json#L10-L15 + - Requires full git sha + - You must provide the full sha. Commands like `https://github.com/owner/repo/blob/$(git rev-parse HEAD)/foo/bar` will not work, since your comment will be directly rendered in Markdown. + - Repo name must match the repo you're code reviewing + - # sign after the file name + - Line range format is L[start]-L[end] + - Provide at least 1 line of context before and after, centered on the line you are commenting about (eg. if you are commenting about lines 5-6, you should link to `L4-7`) diff --git a/.github/workflows/claude-review.yml b/.github/workflows/claude-review.yml new file mode 100644 index 0000000..b172f6c --- /dev/null +++ b/.github/workflows/claude-review.yml @@ -0,0 +1,69 @@ +name: Claude Review + +# Reusable workflow: reviews the calling repository's pull request with the +# code-review skill in this repo (.claude/skills/code-review). Findings are +# posted as inline comments on the diff, with a summary comment when nothing +# is found. Runs against the Claude subscription behind CLAUDE_CODE_OAUTH_TOKEN +# (org secret), so the only added cost is Actions minutes. +# +# Call it from a repo with: +# +# on: +# pull_request: +# types: [opened, synchronize, reopened, ready_for_review] +# jobs: +# review: +# uses: TruFin-io/.github/.github/workflows/claude-review.yml@main +# secrets: inherit + +on: + workflow_call: + inputs: + model: + description: Model for the orchestrating agent; review sub-agents pick their own tier + type: string + default: claude-opus-5 + secrets: + CLAUDE_CODE_OAUTH_TOKEN: + required: true + +jobs: + review: + runs-on: ubuntu-latest + timeout-minutes: 30 + # One review at a time per PR. A new push queues behind the running + # review instead of cancelling it. + concurrency: + group: claude-review-${{ github.event.pull_request.number }} + cancel-in-progress: false + permissions: + contents: read + pull-requests: write + issues: write + steps: + - uses: actions/checkout@v6 + with: + fetch-depth: 0 + persist-credentials: false + + - name: Fetch the shared review skill + uses: actions/checkout@v6 + with: + repository: TruFin-io/.github + path: .trufin-shared + persist-credentials: false + + - name: Install the skill into the reviewed repo + run: | + mkdir -p .claude/skills + cp -r .trufin-shared/.claude/skills/code-review .claude/skills/ + + - uses: anthropics/claude-code-action@v1 + with: + claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + github_token: ${{ github.token }} + allowed_bots: "dependabot[bot]" + prompt: "/code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}" + # The action starts the inline-comment MCP server only when + # --allowedTools names it, even though the skill frontmatter does too. + claude_args: --model ${{ inputs.model }} --allowedTools "mcp__github_inline_comment__create_inline_comment" diff --git a/README.md b/README.md index edcb0d7..9a2e072 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,22 @@ that does not define its own. [Vulnerability Management Policy](https://github.com/TruFin-io/docs) SLAs (Critical 1d / High 3d / Medium 7d / Low 30d). +- **`.github/workflows/claude-review.yml`** – reusable workflow that reviews a + pull request with Claude. Repos call it from their own `claude-review.yml` + (see the header comment in the file). Runs on the org + `CLAUDE_CODE_OAUTH_TOKEN` secret, so it bills the Claude subscription. +- **`.claude/skills/code-review/SKILL.md`** – the review skill that workflow + runs. It is copied into the reviewed repo at run time, so a repo's own + `CLAUDE.md` files drive the compliance checks. Reviews drafts, re-reviews + on every push, and updates its summary comment in place. + Based on Anthropic's [`plugins/code-review/commands/code-review.md`](https://github.com/anthropics/claude-code/blob/main/plugins/code-review/commands/code-review.md), + copied at commit [`db8834b`](https://github.com/anthropics/claude-code/blob/db8834ba1d72e9a26fba30ac85f3bc4316bb0689/plugins/code-review/commands/code-review.md). + To check for upstream changes: + + ```bash + diff <(gh api repos/anthropics/claude-code/contents/plugins/code-review/commands/code-review.md --jq .content | base64 -d) .claude/skills/code-review/SKILL.md + ``` + ## Adding to this repo Defaults only take effect where a repo does not already override them. If you From eac01d6875566eb58423abcbfd33bfd854f154fb Mon Sep 17 00:00:00 2001 From: bokobza Date: Mon, 14 Sep 2026 14:38:47 +0100 Subject: [PATCH 2/3] Skip draft PRs; review starts when a PR is marked ready The reusable job now runs only when the PR is not a draft, so no runner starts and no tokens are spent on work in progress. The ready_for_review trigger in the caller starts the first review. The skill keeps its own draft check as well. Co-Authored-By: Claude Opus 5 --- .claude/skills/code-review/SKILL.md | 3 ++- .github/workflows/claude-review.yml | 2 ++ README.md | 5 +++-- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/.claude/skills/code-review/SKILL.md b/.claude/skills/code-review/SKILL.md index 7fd9fd1..cfaef29 100644 --- a/.claude/skills/code-review/SKILL.md +++ b/.claude/skills/code-review/SKILL.md @@ -14,11 +14,12 @@ To do this, follow these steps precisely: 1. Launch a haiku agent to check if any of the following are true: - The pull request is closed + - The pull request is a draft - The pull request does not need code review (e.g. automated PR, trivial change that is obviously correct) If any condition is true, stop and do not proceed. -Note: Still review Claude generated PRs and draft PRs. This review runs on every push, so a PR that was reviewed earlier is reviewed again for its new head commit. +Note: Still review Claude generated PRs. This review runs on every push, so a PR that was reviewed earlier is reviewed again for its new head commit. 2. Launch a haiku agent to return a list of file paths (not their contents) for all relevant CLAUDE.md files including: - The root CLAUDE.md file, if it exists diff --git a/.github/workflows/claude-review.yml b/.github/workflows/claude-review.yml index b172f6c..e63a829 100644 --- a/.github/workflows/claude-review.yml +++ b/.github/workflows/claude-review.yml @@ -29,6 +29,8 @@ on: jobs: review: + # Drafts are skipped; marking a PR ready for review triggers the first run. + if: github.event.pull_request.draft == false runs-on: ubuntu-latest timeout-minutes: 30 # One review at a time per PR. A new push queues behind the running diff --git a/README.md b/README.md index 9a2e072..12f3b66 100644 --- a/README.md +++ b/README.md @@ -18,8 +18,9 @@ that does not define its own. `CLAUDE_CODE_OAUTH_TOKEN` secret, so it bills the Claude subscription. - **`.claude/skills/code-review/SKILL.md`** – the review skill that workflow runs. It is copied into the reviewed repo at run time, so a repo's own - `CLAUDE.md` files drive the compliance checks. Reviews drafts, re-reviews - on every push, and updates its summary comment in place. + `CLAUDE.md` files drive the compliance checks. Skips drafts (the first + review runs when a PR is marked ready), re-reviews on every push, and + updates its summary comment in place. Based on Anthropic's [`plugins/code-review/commands/code-review.md`](https://github.com/anthropics/claude-code/blob/main/plugins/code-review/commands/code-review.md), copied at commit [`db8834b`](https://github.com/anthropics/claude-code/blob/db8834ba1d72e9a26fba30ac85f3bc4316bb0689/plugins/code-review/commands/code-review.md). To check for upstream changes: From 9f044d3dbcceed1b273c7dbf463adb4740a271f5 Mon Sep 17 00:00:00 2001 From: bokobza Date: Mon, 14 Sep 2026 17:18:54 +0100 Subject: [PATCH 3/3] Address review: comment marker, dedupe on issue identity, hermetic copy The summary comment now carries a `` marker and is only edited when both that marker and the author match, so a human comment that happens to open with the same heading is left alone. Inline-comment dedupe matches file, lines and the underlying problem rather than lines alone, so a new problem on a previously flagged line is still reported. The install step removes any existing code-review skill before copying, so a caller's leftover files cannot survive. Co-Authored-By: Claude Opus 5 --- .claude/skills/code-review/SKILL.md | 4 ++-- .github/workflows/claude-review.yml | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/.claude/skills/code-review/SKILL.md b/.claude/skills/code-review/SKILL.md index cfaef29..5264d7c 100644 --- a/.claude/skills/code-review/SKILL.md +++ b/.claude/skills/code-review/SKILL.md @@ -62,13 +62,13 @@ Note: Still review Claude generated PRs. This review runs on every push, so a PR If `--comment` argument was NOT provided, stop here. Do not post any GitHub comments. - If `--comment` argument IS provided and NO issues were found, post the summary comment and stop. If an earlier run already left a comment starting with `## Code review` on this PR (find it with `gh api repos///issues//comments`), update that comment in place with `gh api --method PATCH repos///issues/comments/ -f body=...` instead of posting a new one. + If `--comment` argument IS provided and NO issues were found, post the summary comment and stop. End the body with the marker `` so later runs can find it. If an earlier run already left a comment on this PR that contains that marker and was written by the same author as this run (find it with `gh api repos///issues//comments`), update that comment in place with `gh api --method PATCH repos///issues/comments/ -f body=...` instead of posting a new one. A comment without the marker belongs to someone else: never edit it. If `--comment` argument IS provided and issues were found, continue to step 8. 8. Create a list of all comments that you plan on leaving. This is only for you to make sure you are comfortable with the comments. Do not post this list anywhere. - Then fetch the inline comments already on the PR with `gh api repos///pulls//comments` and drop from your list any issue that an earlier run already reported on the same lines. An issue that was fixed since it was reported needs no new comment. + Then fetch the inline comments already on the PR with `gh api repos///pulls//comments` and drop from your list any issue an earlier run already reported — the same file, the same lines, and the same underlying problem. A different problem on a line that already carries a comment is still worth reporting. An issue that was fixed since it was reported needs no new comment. 9. Post inline comments for each issue using `mcp__github_inline_comment__create_inline_comment` with `confirmed: true`. For each comment: - Provide a brief description of the issue diff --git a/.github/workflows/claude-review.yml b/.github/workflows/claude-review.yml index e63a829..039fba6 100644 --- a/.github/workflows/claude-review.yml +++ b/.github/workflows/claude-review.yml @@ -58,7 +58,8 @@ jobs: - name: Install the skill into the reviewed repo run: | mkdir -p .claude/skills - cp -r .trufin-shared/.claude/skills/code-review .claude/skills/ + rm -rf .claude/skills/code-review + cp -r .trufin-shared/.claude/skills/code-review .claude/skills/code-review - uses: anthropics/claude-code-action@v1 with: