The README tells contributors which pull requests get the automated Claude review and how a fork PR gets one

[webdevcody]

Nothing in the repository said which pull requests get the automated Claude review or why a fork PR's review fails; the README's Building section now says both, in one paragraph next to the note on how releases are cut.

Contents: 1. The problem · 2. What changed · 3. How it looks · 4. How it works · 5. Risk · 6. Technical overview · 7. Notes

1. The problem

Three contributor PRs in a row (#77, #79, #81) arrived from a fork and each showed the claude-review check failing, before anyone had read the diff. The cause is GitHub's, not the contributor's: a pull_request run of fork code gets no secrets and no OIDC token, so the reviewer cannot authenticate. #82 makes that check skip instead of fail, but the README still told a contributor nothing about what review to expect, or how to get one.

2. What changed

• Who gets the automated review. The README's Building section says a branch pushed to this repository gets a Claude code review on its PR, as inline comments.
• What a fork PR gets instead. The same paragraph says a fork PR does not, names the reason in one clause, and gives the way out: a maintainer reviews by hand or asks for the review with @claude in a PR comment.
• Unchanged. Everything else in the README, and both workflows; this PR touches prose only.

3. How it looks

A README paragraph has no screen to shoot; this is the paragraph as it renders, under Building, after the note on releases:

Pull requests: a branch pushed to this repository gets an automated Claude code review on its PR, as inline comments. A PR from a fork does not — GitHub withholds the credentials the reviewer needs from a fork's workflow runs — so a maintainer reviews it by hand, or asks for the review with @claude in a PR comment.

4. How it works

flowchart LR
  PR[pull request opened] --> Q{head branch lives in this repo?}
  Q -- yes --> AUTO["claude-review runs\ninline comments on the PR"]
  Q -- no, a fork --> SKIP["claude-review skipped (#82)"]
  SKIP --> M[maintainer reads the diff]
  M -- "@claude in a comment" --> BOT["Claude Code workflow\nruns with this repo's credentials"]
  M -- by hand --> DONE[review]
  BOT --> DONE
  AUTO --> DONE

Loading

5. Risk

Verdict: 🟢 Low risk — prose only; nothing that runs is touched.

	Level	Why
🔒 Security & production	Low	No new surface: one paragraph of README; no workflow, code or config changes.
⚡ Performance	Low	Nothing runs: a documentation change.
🧩 Fit with the codebase	Low	Sits beside the existing "Releases:" paragraph in the same section, in the same one-paragraph shape.

Rollback: git revert of the merge removes the paragraph; nothing else to undo.

6. Technical overview

• Mechanism. The paragraph describes the two workflows already in .github/workflows/: the review workflow runs on pull_request and needs the repository's OIDC token and OAuth secret, which GitHub grants to same-repo branches only; the @claude workflow runs on issue_comment in the base repository's context, so a maintainer's comment reaches the reviewer with credentials even on a fork PR.
• Files. README.md — one paragraph added under Building.
• Why not a CONTRIBUTING.md. The README already carries the build and release notes a contributor reads first; one more paragraph there is found, a new file is not.
• Gate. make ci not run: the diff is Markdown only.

7. Notes

• Based on main after README: custom harness guide and supported CLIs with install links #81; independent of The Claude review check skips pull requests from forks instead of failing on them #82, and its own claude-review check is the end-to-end run that The Claude review check skips pull requests from forks instead of failing on them #82's could not be (a PR that edits the review workflow is skipped by the action itself).
• Follows The Claude review check skips pull requests from forks instead of failing on them #82, which makes the fork check read "skipped".

🤖 Generated with Claude Code