Add automated Claude PR review workflow #32

Description

Add a claude-review.yaml workflow modelled on the one in kosli-dev/terraform-provider-kosli: two jobs on pull_request (opened, synchronize, reopened), one for bot dependency PRs and one for human PRs, both using anthropics/claude-code-action with track_progress, use_sticky_comment, a concurrency group, and a 15-minute timeout.

This repo is a good fit — CLAUDE.md already documents the architecture and its invariants, which is exactly the context the general-review prompt reads.

Adaptations needed

1. Fork PRs must be handled explicitly (blocking)

The reference triggers on pull_request unguarded. That's fine on an internal repo. Once this one is public it is not:

• PRs from forks run without repository secrets and with a read-only token, so pull-requests: write isn't granted and the Anthropic credentials are absent. The job fails on every external contributor's PR.
• Switching to pull_request_target to "fix" that is dangerous: it runs with secrets in the base-repo context, so checking out and executing fork code becomes remote code execution. Don't do it without understanding the tradeoff.
• Cost: on a public repo, anyone opening a PR can trigger a paid Claude run.

Recommendation: guard both jobs to same-repo PRs, e.g.

if: github.event.pull_request.head.repo.full_name == github.repository

and revisit fork coverage separately if we want it.

2. Authentication

The reference's header comment says it requires an ANTHROPIC_API_KEY secret, but the with: block actually uses OIDC federation — anthropic_federation_rule_id, anthropic_organization_id, anthropic_service_account_id from repo/org vars, with id-token: write. The comment is stale. We need to decide which route this repo uses and make sure the vars exist here.

3. Pin actions by SHA

The reference uses floating tags (actions/checkout@v7.0.1, anthropics/claude-code-action@v1.0.189). Every action in our three workflows is pinned to a full commit SHA with a version comment, and we run step-security/harden-runner first. The new workflow should match both conventions — and once #20's Dependabot config lands, those pins get maintained automatically.

4. Rewrite the prompts for this codebase

The reference's Phase 1 asks for "well-known Terraform provider patterns" and "general Golang recommendations". For us that should check the invariants in CLAUDE.md:

• The catalog-driven design — three generic tools, no tool per endpoint
• ESM with .js extensions on relative imports; strict: true not weakened
• KosliClient returns the { error: true, ... } shape rather than throwing
• Responses stay compact JSON.stringify (no pretty-printing)
• User-Agent: kosli-mcp-server preserved; org falls back to config.org
• src/catalog.json is generated, not hand-edited

5. Bot job: catalog PRs, not just dependency PRs

Our weekly update-catalog PRs are authored by github-actions[bot], so they'd land in the bot job — but the reference's prompt is about dependency changelogs and semver, which doesn't fit a regenerated catalog.

There's a better job for it. Catalog regeneration can silently remove actions: #16 was exactly that (a stale branch clobbering the catalog), and PR #18 legitimately dropped list_artifact_approvals, which took a manual check against the live OpenAPI spec to confirm. A prompt that diffs the catalog and calls out removed or changed actions — and whether anything in src/ or test/ still references them — would automate that check.

Suggest three cases rather than two: dependency PRs (Dependabot), catalog PRs (update-catalog), and general PRs.

6. Model and budget

The reference pins --model claude-opus-4-8 with --max-turns 40 and --max-budget-usd 5. Worth picking a current model at implementation time and sizing the budget for this repo, which is much smaller than the provider.

Tasks

• Add .github/workflows/claude-review.yaml with SHA-pinned actions + harden-runner
• Guard both jobs against fork PRs
• Confirm the Anthropic auth route and that the required vars/secrets exist here
• Rewrite the general prompt around CLAUDE.md invariants
• Add a catalog-diff prompt for update-catalog PRs
• Choose model and budget