ci: Claude multi-agent PR review workflow by marcelosalloum · Pull Request #67 · stellar/laboratory-backend

marcelosalloum · 2026-05-21T18:04:42Z

Summary

Adds .github/workflows/claude-review.yml — a swarm of five specialist Claude review agents that run in parallel on every PR. Each focuses on one concern and stays in its lane:

Agent	Focus	Skill
`postgres`	Prisma schema, query patterns, N+1, migration safety, pooling	`postgres-optimization`, `database-migrations`
`typescript`	Type narrowing, zod, async, Express 5, idiomatic Node 22+	`productionalize-node`
`docker`	Multi-stage layering, image size, `.dockerignore`, cache order	`docker-patterns`
`security`	Secrets, input validation, AuthN/Z, deps, logging, CORS	`security-audit`
`docs`	README/`.env.example`/Makefile/docs drift introduced by the PR	(prompt-only)

Each agent posts inline comments prefixed with its lane (e.g. [Security Review]) plus one summary PR comment so reviewers see five stacked sections.

Cost

All agents run on claude-haiku-4-5 with --max-turns 25. Per the Slack thread (#dev-tools, 2026-05-13), keeping the model small + the prompts focused keeps spend manageable while still beating Copilot in practice.

Skills are vendored

The five skills the agents reference live under .claude/skills/ in the repo so the GitHub Actions runner can load them with no external setup. security-audit was already present from a prior change; the other four were copied from local sources (dereferenced via cp -RL — the originals are symlinks).

Security model

Borrowed from stellar/actions#103 (stellar/actions#103):

Trigger is pull_request (not pull_request_target) — laboratory-backend doesn't accept fork contributions, so the safer default is fine. Secrets are stripped on fork PRs by GitHub, which is the desired behavior here.
Workflow-level permissions: {}; job opts in to contents: read, pull-requests: write, id-token: write.
Tool allowlist scopes gh pr commands to the current PR number explicitly.
Concurrency group is per-(PR, aspect) so new pushes cancel stale runs of the same aspect without cancelling sibling agents.

Once stellar/actions#103 merges and grows model selection, we should migrate to the reusable workflow there and drop the local copy of the security boilerplate.

Required setup

ANTHROPIC_API_KEY must be present as a repo secret.

Test plan

Confirm ANTHROPIC_API_KEY is configured in repo secrets.
On opening this PR, all five jobs in Claude Multi-Agent Review should run.
Each agent should post a summary comment headed ## <Title> Review.
Inline comments (if any) should be prefixed [<Title>].
Verify cost on the Anthropic console — should be cheap (Haiku, ~25 turns max per agent).

Adds a swarm of five specialist Claude review agents that run in parallel on each PR, one per concern (PostgreSQL, TypeScript, Docker, security, docs). Each agent loads a domain-specific skill from `.claude/skills/` and posts inline + summary comments scoped to its lane. All agents run on `claude-haiku-4-5` to keep cost low. Security model is borrowed from stellar/actions PR #103, but uses `pull_request` (not `_target`) since this repo doesn't accept fork contributions. The five skills are vendored under `.claude/skills/` so the CI runner can load them without external dependencies.

marcelosalloum · 2026-05-21T18:06:35Z

Note on this PR's empty review

The five review jobs ran on this PR but each self-skipped with:

Workflow validation failed. The workflow file must exist and have identical content to the version on the repository's default branch. If you're seeing this on a PR when you first add a code review workflow file to your repository, this is normal and you should ignore this error.

This is a built-in safety check in anthropics/claude-code-action@v1: it refuses to run when the workflow file on the PR differs from main. That prevents an attacker from modifying the workflow on a PR to exfiltrate secrets.

Once this PR merges, the workflow will fire normally on subsequent PRs. No further config is needed — ANTHROPIC_API_KEY is already present (the action printed anthropic_api_key: ***).

To verify end-to-end after merging: open a small follow-up PR with any code change and confirm all five agents post their summary comments.

Copilot

Pull request overview

Adds a GitHub Actions workflow that runs five parallel Claude review “lanes” on each pull request, and vendors the referenced lane “skills” into the repo so the action can load them without external setup.

Changes:

Introduces .github/workflows/claude-review.yml to run a matrix of five specialist review jobs (Postgres, TypeScript, Docker, Security, Docs) and post PR comments.
Vendors multiple Claude skills under .claude/skills/ (including Postgres optimization, Docker patterns, database migrations, and a productionalize-node playbook) for the agents to load.
Adds a verification-focused skill intended to prevent “claims without evidence”.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
.github/workflows/claude-review.yml	New multi-agent PR review workflow using a matrix of five aspects and a restricted tool allowlist.
.claude/skills/verification-before-completion/SKILL.md	New skill text emphasizing running verification commands before declaring completion.
.claude/skills/productionalize-node/SKILL.md	New “productionalize-node” skill defining an assessment/execution playbook for hardening a Node/TS codebase.
.claude/skills/productionalize-node/references/tooling-defaults.md	Reference doc listing a default tooling stack and alternatives.
.claude/skills/productionalize-node/references/phase-8-final-review.md	Reference doc describing final review steps and completion criteria.
.claude/skills/productionalize-node/references/phase-7-documentation.md	Reference doc for README/docs/CHANGELOG updates and verification.
.claude/skills/productionalize-node/references/phase-6-ci.md	Reference doc with an example CI workflow and CI best-practice notes.
.claude/skills/productionalize-node/references/phase-5-testing.md	Reference doc describing Vitest setup, coverage workflow, and test conventions.
.claude/skills/productionalize-node/references/phase-4-dependencies.md	Reference doc for audits/upgrades plus a “dependency freshness” gate script.
.claude/skills/productionalize-node/references/phase-3-hardening/phase-3.5-cors-evaluation.md	Reference doc for deciding whether to configure CORS and how to verify it.
.claude/skills/productionalize-node/references/phase-3-hardening/phase-3.4-env-validation.md	Reference doc for centralized env validation via t3-env + Zod.
.claude/skills/productionalize-node/references/phase-3-hardening/phase-3.3-security.md	Reference doc for baseline Express security hardening (helmet, rate limiting, secrets audit).
.claude/skills/productionalize-node/references/phase-3-hardening/phase-3.2-input-validation.md	Reference doc for boundary validation using Zod schemas/middleware.
.claude/skills/productionalize-node/references/phase-3-hardening/phase-3.1-error-handling.md	Reference doc for establishing an error hierarchy and error middleware patterns.
.claude/skills/productionalize-node/references/phase-3-hardening/phase-3-hardening.md	Reference doc describing Phase 3 sequencing and verification gates.
.claude/skills/productionalize-node/references/phase-2-quality-infra.md	Reference doc for ESLint/Prettier setup and structured logging guidance.
.claude/skills/productionalize-node/references/phase-1-foundation.md	Reference doc for TS strict migration, scripts/Makefile, and repo hygiene.
.claude/skills/productionalize-node/references/assessment-checklist.md	Reference doc providing an assessment checklist for production readiness.
.claude/skills/postgres-optimization/SKILL.md	New Postgres optimization skill covering indexing, plans, partitioning, pooling, and diagnostics.
.claude/skills/docker-patterns/SKILL.md	New Docker patterns skill covering Compose, Dockerfile hygiene, and container security.
.claude/skills/database-migrations/SKILL.md	New database migration patterns skill with safety checklists and ORM-specific guidance.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+# Group by PR + aspect so a new push cancels stale runs of the same
+# aspect, but parallel aspects on the same PR don't cancel each other.
+concurrency:
+  group: claude-review-${{ github.event.pull_request.number }}-${{ github.job }}


+        with:
+          fetch-depth: 0
+
+      - uses: anthropics/claude-code-action@v1


+   for (const [name, version] of Object.entries(allDeps)) {
+     try {
+       const raw = execSync(`npm view ${name} time --json`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] })
+       const times = JSON.parse(raw)


+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4


Addresses two issues Copilot caught on the PR: 1. The workflow-level concurrency.group used ${{ github.job }}, which resolves to the constant job id "review" for every matrix entry. All five agents shared one group and would have cancelled each other. Workflow-level concurrency can't reference matrix.*, so the group moves to the job level and keys on matrix.id. 2. Pin anthropics/claude-code-action to a commit SHA (matching the existing convention for third-party actions in this repo) to reduce supply-chain risk. SHA is the current v1 tag.

marcelosalloum · 2026-05-21T18:17:25Z

Re-pushed addressing Copilot review

Two real bugs Copilot caught:

Concurrency group collapse (claude-review.yml:28). ${{ github.job }} is the literal job id review, identical across all five matrix entries — they'd have cancelled each other. Moved the group to the job level (where matrix.* is resolvable) and keyed on matrix.id. Workflow-level concurrency can't use matrix context, so the group has to live on the job.
Unpinned third-party action. anthropics/claude-code-action@v1 is now pinned to 20c8abf165d5f85ab3fc970db9498436377dc9d1, matching the repo's convention (e.g. docker/login-action@c94ce9fb... in build.yml).

The two other Copilot comments touch vendored skill markdown (phase-4-dependencies.md, phase-6-ci.md) — both real (shell interpolation in a freshness check, drift in example action versions) but those files are reference docs that agents read, not code that executes, so I'll leave them for follow-up to keep this PR scoped to wiring up the workflow.

Copilot AI review requested due to automatic review settings May 21, 2026 18:04

github-project-automation Bot added this to DevX May 21, 2026

github-project-automation Bot moved this to Backlog (Not Ready) in DevX May 21, 2026

Copilot started reviewing on behalf of marcelosalloum May 21, 2026 18:05 View session

Copilot AI reviewed May 21, 2026

View reviewed changes

marcelosalloum mentioned this pull request May 21, 2026

ci: Claude multi-agent PR review workflow stellar-experimental/laboratory-backend#1

Merged

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ci: Claude multi-agent PR review workflow#67

ci: Claude multi-agent PR review workflow#67
marcelosalloum wants to merge 2 commits into
mainfrom
claude-multi-agent-review

marcelosalloum commented May 21, 2026

Uh oh!

marcelosalloum commented May 21, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

marcelosalloum commented May 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

marcelosalloum commented May 21, 2026

Summary

Cost

Skills are vendored

Security model

Required setup

Test plan

Uh oh!

marcelosalloum commented May 21, 2026

Note on this PR's empty review

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

marcelosalloum commented May 21, 2026

Re-pushed addressing Copilot review

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants