Add reusable Claude Code review workflow

[mahangu]

@kraftbj @anomiex @lezama Adding y'all bc you touched Claude workflows in this repo. 🙏🏾

Proposed changes

• Add .github/workflows/claude-review-shared.yml — a workflow_call reusable workflow that other Automattic repos can call to get the same AI review behavior as claude.yml. Sparse-checks-out this monorepo's .agents/skills/jetpack-review-pr.md + .claude/commands/*.md at runtime, then runs anthropics/claude-code-action. Single source of truth for the skill stays here.
• Includes a caller-org guard that rejects invocations from outside the Automattic org (mirrors the pattern in woocommerce/.github's reusable AI-review workflow). The reusable lives in a public repo, so the guard makes the support contract explicit.
• claude.yml is unchanged.

Related product discussion/links

• Linear: QAO-424 - rolling this out to JPOP-Happiness-touched Jetpack satellites (jetpack-crm, jetpack-videopress, WP-Job-Manager).
• Companion PR on Automattic/jetpack-videopress necessary to add the first satellite caller. https://github.com/Automattic/jetpack-videopress/compare/add/ai-code-review

Does this pull request change what data or activity we track or use?

No. Same action, same key, same skill, same review output.

Testing instructions

The reusable workflow has no observable behavior in this repo on its own (no events trigger it directly). End-to-end test runs through the satellite caller PR: once both land, drop `@claude /jetpack-review-pr quick` on a `jetpack-videopress` PR (MEMBER/OWNER) and verify a review posts back.

[github-actions]

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

• ✅ Include a description of your PR changes.
  
• ✅ Add a "[Status]" label (In Progress, Needs Review, ...).
  
• ✅ Add testing instructions.
  
• ✅ Specify whether this PR includes any changes to data or privacy.
  
• ✅ Add changelog entries to affected projects
  

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

---

Follow this PR Review Process:

1. Ensure all required checks appearing at the bottom of this PR are passing.
2. Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
3. You can use GitHub's Reviewers functionality to request a review.
4. When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

[mahangu]

@claude /jetpack-review-pr 48312 quick

[claude]

Claude finished @mahangu's task in 54s —— View job

---

Claude Code Review — PR #48312

• Gather context
• Read workflow file
• Provide review feedback

---

Overall: Clean, well-structured approach. The design (sparse-checkout of skills from trunk, copy into caller workspace) is sound and achieves the "single source of truth" goal. A few things worth double-checking:

---

Potential Issues

1. actions/checkout@v6 may not exist

Both checkout steps use actions/checkout@v6 (lines 34 and 39). As of the most recent stable release I'm aware of, actions/checkout is on v4. If v6 isn't published, every satellite caller workflow will fail at checkout. Please verify this version exists, or pin to v4 (or whichever is latest stable).

2. Supply-chain risk: Jetpack sparse-checkout is pinned to trunk HEAD

ref: trunk

Any commit pushed to trunk — including a bad one — is immediately live for all satellite callers on their next run. This is the intended "single source of truth" tradeoff, but it means a compromised or accidentally broken skill file would affect all callers with zero delay. Consider whether a SHA pin or a release tag ref would be safer, even at the cost of requiring manual bumps. At minimum, document this risk clearly for callers.

3. id-token: write with no visible OIDC usage

The job declares id-token: write (line 31), which matches claude.yml. If this is needed by claude-code-action internally, that's fine — but callers may be surprised by this permission requirement. A brief comment explaining why it's needed (or confirming the action requires it) would help.

---

Minor Notes

• The .jetpack-shared/ directory is left in the caller's workspace after the copy step. It's harmless, but if you want a tidy workspace, a rm -rf .jetpack-shared at the end of the wire-up step or as a cleanup step would keep things clean.
• The caller docs (PR description) correctly note that trigger filtering (author_association checks, event types) is the caller's responsibility. Consider adding a brief note in the workflow's top comment block pointing to claude.yml as a reference implementation, so satellite maintainers have a concrete example.
• No github_token is explicitly passed to claude-code-action, which is consistent with claude.yml — the action presumably uses GITHUB_TOKEN from the environment. This should work fine.

---

Verdict: Approve once the actions/checkout@v6 version is confirmed. The other items are low-priority but worth addressing before broader rollout.

[mahangu]

Thanks Claude. Pushed an amendment commit (e30ab62). Going through:

1. actions/checkout@v6: verified. v6.0.0 shipped 2025-11-20, currently v6.0.2. Jetpack's existing claude.yml is already on @v6. Keeping as-is.

2. ref: trunk supply chain: this is the explicit "single source of truth" design tradeoff. A SHA-pin or release-tag would put us back to mirroring. Documented the tradeoff in the top-of-file comment, including the option for satellites to SHA-pin the reusable workflow's uses: line for defense in depth (skill content stays on trunk).

3. id-token: write: required by claude-code-action (verified empirically; the action mints an OIDC token for the claude[bot] identity). Documented in the top-of-file comment alongside the rest of the permissions semantics, which felt cleaner than annotating the line itself.

4. .jetpack-shared/ cleanup: agreed, added rm -rf .jetpack-shared at the end of the wire-up step.

5. Caller responsibility note: top-of-file comment now points at claude.yml as the reference caller.

6. github_token: action reads it from env. Reusable's permissions block is authoritative for the satellite's GITHUB_TOKEN; called that out in the top-of-file comment.

[mahangu]

@claude /jetpack-review-pr 48312 quick

[claude]

Claude finished @mahangu's task in 58s —— View job

---

Claude Code Review — PR #48312

• Gather context
• Read workflow file
• Provide review feedback

---

All five items from the previous review have been cleanly addressed in e30ab62. The top-of-file comment block is thorough and will be genuinely useful for satellite maintainers — the OIDC job_workflow_ref note in particular is easy to overlook and worth having documented.

One minor observation remaining:

additional_permissions: actions: read is redundant (line 89–90). actions: read is already declared in the job-level permissions block (line 54), which is the authoritative scope for GITHUB_TOKEN. The additional_permissions input to claude-code-action likely serves a different purpose inside the action itself — if so, it's harmless but worth a quick confirmation that it's intentional and not a copy-paste from a template. If it's not needed, removing it reduces confusion for satellite readers trying to understand the permission model.

Everything else looks correct:

• rm -rf .jetpack-shared is present and in the right place (end of wire-up step).
• The action is SHA-pinned (@df37d2f...) with a # v1 comment — good practice.
• sparse-checkout-cone-mode: false is correct for the non-standard .agents/ path.
• >- YAML block scalar correctly folds the multi-line claude_args into a single string.
• The ANTHROPIC_API_KEY opaque-failure note in the comment is a nice touch for satellite onboarding.

Verdict: Approve. The additional_permissions redundancy is worth a look but not a blocker.

[mahangu]

additional_permissions: actions: read is redundant (line 89–90).

Kept for parity with claude.yml line 48. If unnecessary, will clean up in a follow-up PR.

[tbradsha]

I'll note that I'm a bit confused as to what this PR is trying to add. Is it for the Jetpack monorepo, or for other repos?

I also would highly recommend encouraging collaboration between Happiness and the agent and such iterations to be done locally rather within a PR if we're also expecting human reviewers, as skimming through PR iterations is a high burden for humans.

That said, a few notes:

• Jetpack-adjacent mirror repos don't support PRs (e.g. jetpack-crm and jetpack-videopress). All development is done in the monorepo.
• Were we wanting to copy/use a workflow from the monorepo to a mirror repo (which I'm still not sure we want to do), I'd recommend sticking to the pattern used elsewhere like we have with autotagger and a few other workflows, putting it in a .github/files/gh-*/workflowsdir.
• The skills it's referencing use monorepo-specific references (e.g. project//) and commands like jp build, and have monorepo changelog and label instructions. They won't be of any use in mirror repos.
• The permissions we're granting are quite broad (e.g. gh pr *), though that's similar to what's done in claude.yml.
• The workflow name itself seems misleading. If it's for reviews, why are we copying all the other skills?

More generally, what's the advantage of having this done in a GitHub Action vs. as an AI skill locally that looks at the PR?