refactor(agents): Extract and enhance 6 reviewer agents

[yamadashy]

Extract inline review agent descriptions from review-loop.md and pr-review.md into dedicated, reusable agent definitions under .agents/agents/.

Each reviewer agent is enriched with research-backed best practices while keeping content general (not project-specific):

• reviewer-code-quality — Severity levels, 8 focus areas (bugs, async/concurrency, resource management, error handling, API contracts, type safety, code smells, test quality), structured output format
• reviewer-security — CWE references, OWASP Top 10:2025 alignment, 11 categories including Node.js-specific risks (prototype pollution, ReDoS, supply chain)
• reviewer-performance — V8 optimization hints, event loop patterns, data structure selection, explicit flagging threshold criteria
• reviewer-test-coverage — Risk-based prioritization table, 5 test design techniques (equivalence partitioning, boundary value analysis, etc.), 10 test smells, mutation testing mental model
• reviewer-conventions — 3-step methodology (discover → check → evaluate tension), documentation accuracy, export consistency, commit/PR conventions
• reviewer-holistic — Gary Klein's premortem technique, change impact analysis, contract/compatibility checks, blast radius evaluation, user/operator impact

Command files (review-loop.md, pr-review.md) now reference agent names only, eliminating duplication.

Checklist

• Run npm run test
• Run npm run lint

---

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 14c85b5d-7661-4d25-b865-f4cbf1de1175

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR introduces six specialized AI reviewer agent definitions (code quality, security, performance, test coverage, conventions, and holistic) and updates the review workflow documentation to reference these agents by explicit identifiers instead of generic angle-based descriptions. A pointer file is added for convenience.

Changes

Cohort / File(s)	Summary
New Reviewer Agent Definitions .agents/agents/reviewer-code-quality.md, .agents/agents/reviewer-security.md, .agents/agents/reviewer-performance.md, .agents/agents/reviewer-test-coverage.md, .agents/agents/reviewer-conventions.md, .agents/agents/reviewer-holistic.md	Six new documentation files defining specialized reviewer roles with severity taxonomies, focus areas, output formats, and review guidelines (e.g., code quality checks, security risk identification, performance analysis, test coverage gaps, convention violations, cross-cutting architectural concerns).
Review Workflow Updates .agents/commands/code/review-loop.md, .agents/commands/git/pr-review.md	Updated review workflow documentation to reference the six reviewer agents by explicit identifiers (reviewer-code-quality, reviewer-security, etc.) instead of generic "Agent 1–6" or angle-based descriptions.
Utility Pointer .claude/agents	New file pointing to ../.agents/agents directory for convenience access.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• chore(cli): Add review-loop command #1285 — Modifies .agents/commands/code/review-loop.md with agent list updates; directly related workflow change.
• refactor(cli): Use multi-agent parallel review in pr-review command #1286 — Makes equivalent changes to .agents/commands/git/pr-review.md by introducing the same six named parallel reviewer agents.
• chore(config): Move commands to .agents directory and add symlinks #826 — Reorganizes agent configuration into .agents directory and adds pointer files in .claude/.cursor for backward compatibility; similar organizational pattern.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: extracting inline reviewer descriptions into dedicated, reusable agent definitions and enhancing them with best practices.
Description check	✅ Passed	The description comprehensively covers the PR objectives, lists all six reviewers with their key enhancements, and includes completed checklist items; however, it lacks detail on the .claude/agents file addition.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/extract-review-agents

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cloudflare-workers-and-pages]

Deploying repomix with    Cloudflare Pages

Latest commit:	554a589
Status:	✅  Deploy successful!
Preview URL:	https://c5b4cf81.repomix.pages.dev
Branch Preview URL:	https://refactor-extract-review-agen.repomix.pages.dev

View logs

[claude]

Code Review

Clean refactoring that extracts inline reviewer agent descriptions into dedicated, reusable definition files. The new agent definitions are substantially more thorough than the original one-liners -- a clear net positive. No production code changes, so integration risk to the Repomix codebase is zero.

Findings

1. Ambiguous phrasing about ?? in reviewer-code-quality.md (Recommended fix)

The Null/undefined bullet says:

nullish coalescing (??) with falsy-but-valid values like 0 or ""

This reads as a warning against using ?? with 0/"", but ?? is the correct operator for those cases (it only triggers on null/undefined). The actual bug pattern to flag is using || instead of ??. Since this prompt guides AI reviewers, imprecise phrasing here could cause false positives.

Suggested rewrite:

logical OR (||) used as a default where nullish coalescing (??) is needed, causing falsy-but-valid values like 0 or "" to be incorrectly replaced

2. Inconsistent output format across the 6 agent files (Consider standardizing)

The agents define four different output styles:

• Bold label + bullets: reviewer-code-quality.md
• Numbered list: reviewer-conventions.md, reviewer-performance.md, reviewer-security.md
• Fenced code block with heading levels: reviewer-test-coverage.md
• Prose in Guidelines section: reviewer-holistic.md (also uses ## Output Guidelines instead of separate ## Output Format + ## Guidelines)

Since these agents run in parallel and their findings are triaged together, inconsistent output formats make the triage step harder to parse. Consider standardizing on one format template.

3. Command files lost orchestration context (Suggestion)

The command files previously gave the orchestrating agent a quick summary of each reviewer's focus area. Now they list only bare names. This slightly reduces the orchestrator's ability to anticipate and deduplicate findings during triage.

Consider adding one-line annotations:

- reviewer-code-quality  <!-- bugs, logic errors, edge cases -->
- reviewer-security      <!-- vulnerabilities, injection, secrets -->

This preserves triage context without duplicating the full definitions.

Details: Additional observations (no action needed)

• Symlink portability: .claude/agents → ../.agents/agents follows the same pattern as the existing .claude/commands symlink. Windows contributors with core.symlinks=false will see a plain text file, but this is a pre-existing accepted risk.
• No security concerns: The symlink stays within the repo boundary, no executable content added.
• No performance concerns: Docs-only change.
• No test coverage gaps: No behavioral code changes to test.
• PR conventions: Title follows Conventional Commits, checklist is present, all files under 250-line limit.

---

🤖 Generated with Claude Code

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 8 additional findings.

[claude]

Code Review

Overall: Clean, well-structured refactoring. The extraction of reviewer agents into dedicated files with detailed, research-backed instructions is a solid improvement. No blocking issues found.

Findings

No issues found in: Security, Performance, Test Coverage — this is purely a documentation/configuration refactoring with no application code changes.

Minor observations (non-blocking)

1. Agent name coupling between command files and agent definitions

Both command files now reference agents by bare name (e.g., reviewer-code-quality). These must exactly match filenames under .claude/agents/. A future rename of one file without updating the command files would silently break the review pipeline. Consider adding a brief comment in the command files listing expected filenames to make the coupling visible.

2. Asymmetry between review-loop.md and pr-review.md

pr-review.md includes a section on evaluating existing AI bot inline comments before spawning reviewers. review-loop.md does not. If both commands drive similar workflows, this omission could cause duplicate findings in loop iterations. This may be intentional (loop operates on local branches without PRs), but worth confirming.

3. reviewer-conventions.md references .agents/rules/ path

Line 15 instructs agents to read project rules files from .agents/rules/. This should work fine since agents operate from the repo root, but worth verifying that spawned sub-agents resolve paths relative to the repo root rather than their definition file location.

Positives

• All six agents share the "report only noteworthy findings" philosophy, preventing noise accumulation
• The holistic agent explicitly lists what sibling reviewers cover, reducing duplication
• Severity vocabularies are appropriately domain-specific rather than forced into a single scale
• The conventions agent distinguishes deviation from discussion, avoiding PR blocking on style improvements
• The symlink pattern is consistent with the existing .claude/commands symlink

LGTM

---

Reviewed with Claude Code