Add Claude Code Action-compatible review agents and improve /review-pr

.agents/skills/local-qa/scripts/qa.sh

@@ -9,7 +9,13 @@ npx -y prettier --write './**/*.md'
 # YAML
 git ls-files -z -- '*.yml' | xargs -0 -t uvx yamllint -d '{"extends": "relaxed", "rules": {"line-length": "disable"}}'
 
+# Shell scripts
+git ls-files -z -- '*.sh' '*.bash' '*.bats' | xargs -0 -t shellcheck
+
 # GitHub Actions
 zizmor --fix=safe .github/workflows
 git ls-files -z -- '.github/workflows/*.yml' | xargs -0 -t actionlint
 checkov --framework=all --output=github_failed_only --directory=.
+
+# OpenCode agent frontmatter and review-pr references
+./.agents/skills/local-qa/scripts/validate-opencode.sh

.agents/skills/local-qa/scripts/validate-opencode.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Validate .opencode/ agent frontmatter and review-pr command/skill references.
+set -euo pipefail
+cd "$(git rev-parse --show-toplevel)"
+
+agents_dir=".opencode/agents"
+docs=(.opencode/commands/review-pr.md .opencode/skills/review-pr/SKILL.md)
+required_keys=(name description mode permission)
+# Backtick-quoted identifiers in the docs that are skills/toolkits, not agents.
+non_agents=(pr-feedback-triage pr-review-toolkit)
+fail=0
+
+warn() { echo "ERROR: $*" >&2; fail=1; }
+
+shopt -s nullglob
+
+# 1. Every agent markdown file has YAML frontmatter with required keys.
+for f in "$agents_dir"/*.md; do
+  fm="$(awk 'NR==1 && /^---$/ {f=1; next} f && /^---$/ {exit} f' "$f")"
+  if [[ -z "$fm" ]]; then
+    warn "$f has no YAML frontmatter"
+    continue
+  fi
+  for key in "${required_keys[@]}"; do
+    grep -qE "^${key}:" <<<"$fm" || warn "$f missing frontmatter key: $key"
+  done
+  name="$(grep -E '^name:' <<<"$fm" | head -1 | sed -E 's/^name:[[:space:]]*//; s/[[:space:]]*$//')"
+  base="$(basename "$f" .md)"
+  [[ "$name" == "$base" ]] || warn "$f name '$name' != filename '$base'"
+done
+
+# 2. Every agent name referenced in review-pr docs exists under .opencode/agents/.
+# Build the backtick-delimited pattern without literal backticks in quotes, so
+# SC2016 (single-quoted backticks looking like expansion) is not triggered.
+bt=$(printf '\x60')
+pattern="${bt}[a-z][a-z0-9]+(-[a-z0-9]+)+${bt}"
+mapfile -t refs < <(
+  grep -hoE "$pattern" "${docs[@]}" \
+    | tr -d "$bt" | sort -u
+)
+for ref in "${refs[@]}"; do
+  skip=0
+  for na in "${non_agents[@]}"; do
+    [[ "$ref" == "$na" ]] && skip=1
+  done
+  [[ "$skip" -eq 1 ]] && continue
+  [[ -f "$agents_dir/$ref.md" ]] || warn "referenced agent '$ref' has no file under $agents_dir/"
+done
+
+if [[ "$fail" -ne 0 ]]; then
+  exit 1
+fi
+echo "OK: agent frontmatter and review-pr references valid."

.agents/skills/pr-feedback-triage/SKILL.md

@@ -43,9 +43,10 @@ When a mode disables an action, skip that destructive or externally visible acti
 
 Gather the complete feedback set before editing:
 
-- Fetch unresolved review threads, requested-change reviews, PR-level summary comments, and copied comments.
+- Fetch unresolved review threads, requested-change reviews, inline comments, copied comments, and PR-level summary comments.
 - Use platform-native APIs/CLI when available. Paginate results; do not inspect only the first page of threads or comments.
-- For bot reviewers that post both summary comments and inline comments, collect both. Summary comments often contain severity, rationale, and fix instructions; inline comments contain the exact file and line context.
+- For bot reviewers that post both summary comments and inline comments, prefer inline comments for actionable triage. Incorporate summary findings only when they contain distinct severity, rationale, or fix instructions not already captured from inline comments.
+- Summary comments may be excluded from triage when they do not add distinct actionable context.
 - Preserve every thread/comment identifier needed to reply or resolve later.
 - Compare each comment with the current diff and file contents because review lines can become outdated.
 
@@ -56,7 +57,7 @@ Build one triage record per distinct finding:
 - Prefer exact review-thread identity when available.
 - For duplicate bot findings appearing in both summary and inline comments, merge by exact issue title first, then by file path plus line range as a fallback.
 - Prefer inline comments for location and current code context.
-- Prefer summary comments for severity, category, rationale, and detailed agent prompts.
+- Use summary comments only for distinct severity, category, rationale, or detailed agent prompts that are not already available from inline comments.
 - Preserve the reviewer’s exact issue title and original wording where practical. Do not rename findings in a way that would make replies hard to map back to comments.
 - Preserve the reviewer’s original ordering unless the user asks for priority reordering. Many review bots already order findings by severity.
 
@@ -70,13 +71,20 @@ Keep a thread open only when it still needs reviewer, maintainer, or product inp
 
 When resolving a thread, add a concise reply first only if it provides useful context, such as what changed, why no code change was needed, why a finding was intentionally deferred, or why the original comment is now outdated. Do not add noisy replies for self-evident fixes unless project norms require them.
 
+## Platform Comment Style
+
+- Keep every posted reply or comment brief: one sentence by default, two short sentences only when necessary.
+- Do not post PR-level summary or status comments by default. Omit them when they only restate completed fixes, resolved threads, or verification already visible in commits/checks.
+- Avoid templates, long bullet lists, exhaustive status logs, and duplicated explanations in platform comments.
+- For simple fixes, already-addressed findings, or outdated findings, prefer `resolve_only` over adding a reply.
+
 ## Platform Action Contract
 
-Do not treat triage as complete until every collected source ID reaches an explicit terminal state:
+Do not treat triage as complete until every incorporated source ID reaches an explicit terminal state:
 
 - `resolved`: a platform resolve action succeeded, or a re-check shows the thread is already resolved.
 - `replied_left_open`: a reply or question was posted and the thread is intentionally left unresolved.
-- `not_resolvable`: the source is a PR-level summary comment or copied comment that has no platform-level resolve action; reply or post a PR summary when useful.
+- `not_resolvable`: the source is a PR-level summary comment or copied comment that has no platform-level resolve action; post a brief reply only when useful.
 - `skipped_by_mode`: `dry_run`, `no_push`, or `no_reply` prevented the external action.
 - `failed_action`: a reply or resolve action was attempted and failed; include the attempted action and failure in the final summary.
 
@@ -85,7 +93,7 @@ In normal mode, build and execute a platform action queue after fixes are verifi
 - `reply_then_resolve`: use for handled threads where the reviewer needs context before resolution.
 - `resolve_only`: use for self-evident fixes and already-addressed or outdated threads where an extra reply would add noise.
 - `reply_leave_open`: use only for clarification requests, blocked work, or intentionally open follow-ups.
-- `reply_only`: use for PR-level comments or summaries that cannot be resolved as review threads.
+- `reply_only`: use for PR-level comments or summaries that cannot be resolved, only when a short reply adds value.
 
 For duplicate findings, execute the terminal action for every source thread ID, not only the primary triage record. If one finding is represented by three unresolved inline threads, all three must be resolved or explicitly left open.
 
@@ -150,9 +158,9 @@ flowchart TD
 ## Compact Workflow
 
 1. **Collect all relevant feedback**
-   - Identify the PR and gather unresolved review threads, requested-change reviews, PR-level summaries, inline comments, and copied comments.
+   - Identify the PR and gather unresolved review threads, requested-change reviews, inline comments, copied comments, and PR-level summaries.
    - Paginate all platform calls and keep comment/thread IDs for later replies and resolution.
-   - For bot reviews, collect both summary and inline comments, then merge duplicates rather than fixing the same finding twice.
+   - For bot reviews, prioritize inline comments and incorporate summary findings only when they add distinct actionable context.
 
 2. **Classify each triage record**
    - **Fix**: Valid requested change; make the smallest focused edit when not in `dry_run`.
@@ -168,7 +176,7 @@ flowchart TD
    - In `dry_run`, stop at triage, proposed fixes, suggested replies, and verification plan.
    - In `no_push`, local edits are allowed, but do not push or resolve threads whose fix is only local. Reply or resolve non-code, already-addressed, or outdated threads only when the action does not depend on unpushed work and `no_reply` is not set.
    - In `no_reply`, do not post replies or resolve threads; report suggested replies/actions instead.
-   - In normal mode, commit and push changed code when appropriate, then execute the platform action queue for every collected source ID.
+   - In normal mode, commit and push changed code when appropriate, then execute the platform action queue for every incorporated source ID.
 
 4. **Verify before claiming completion**
    - For fixes, run appropriate checks or explain why they could not run.
@@ -178,15 +186,16 @@ flowchart TD
    - If a resolve or reply operation fails, retry once when safe; then report `failed_action` with the affected source ID and reason.
 
 5. **Finish**
-   - Normal mode: commit/push changes when appropriate, post useful replies or a summary, resolve all handled threads by default, and reconcile the final unresolved set.
+   - Normal mode: commit/push changes when appropriate, post only useful short replies/comments, omit PR-level summaries when they add no value, resolve all handled threads by default, and reconcile the final unresolved set.
    - Safe modes: report the local state and the exact replies/resolution actions a human could take.
 
 ## Reply Guidance
 
-- Keep inline replies short and tied to the original title or concern.
-- For fixed findings, mention the concrete change or commit if useful.
-- For already-addressed or outdated findings, cite the current code path or behavior that makes the finding no longer applicable.
+- Keep inline replies short: one sentence by default, two short sentences only when needed.
+- For fixed findings, mention the concrete change or commit only if it helps the reviewer.
+- For already-addressed or outdated findings, cite the current code path or behavior only as briefly as needed.
 - For deferred or won't-fix findings, provide the reason and any follow-up issue or owner if known.
+- Avoid posting PR-level summary comments unless they communicate a decision, blocker, or requested reviewer action.
 - If a reply or resolve operation fails, continue with the remaining threads and report the failure in the final summary.
 
 ## Final Summary Checklist

.github/workflows/opencode.yml

@@ -48,7 +48,7 @@ jobs:
           OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}
           GH_TOKEN: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN }}
         with:
-          model: opencode-go/minimax-m3
+          model: opencode-go/kimi-k2.7-code
           prompt: /review-pr
   opencode-bot:
     if: >

.opencode/agents/code-quality-reviewer.md

@@ -0,0 +1,83 @@
+---
+name: code-quality-reviewer
+description: Reviews code changes for general quality, maintainability, clean code principles, edge cases, robustness, and type safety. Use after implementing any feature or change, before creating a pull request, or when reviewing a PR for general quality concerns. Triggers on "review code quality", "check maintainability", "review this for quality", or when quality or code aspects are requested.
+mode: all
+color: success
+permission:
+  edit: deny
+---
+
+You are an expert code quality reviewer with deep expertise in software engineering principles, clean code, and maintainability across multiple languages and frameworks. Your mission is to identify quality issues that affect long-term maintainability and correctness, keeping false positives low.
+
+## When to invoke
+
+Three representative scenarios:
+
+- **Feature PR quality pass.** A PR introduces new functionality. Review the changed code for quality issues — unclear logic, missing edge cases, violation of clean code principles, or inadequate robustness.
+- **Proactive review after implementation.** The assistant has just written new code and wants to catch quality issues before declaring the task done. Focus on the changed lines.
+- **Pre-merge quality check.** Before merging, run a quality pass over the full diff to catch anything missed in the initial review.
+
+## Review Scope
+
+Review only the changed lines (the diff) and the functions they belong to. Do not audit the entire repository.
+
+## Core Review Responsibilities
+
+**Code Clarity and Maintainability:**
+
+- Identify unclear or confusing logic that would slow down future maintainers
+- Flag overly complex conditionals or deeply nested control flow that could be simplified
+- Detect missing abstraction or poor separation of concerns
+- Check for meaningful naming — variables, functions, parameters, and types should communicate intent
+- Identify code duplication that introduces divergence risk
+
+**Correctness and Edge Cases:**
+
+- Identify missing edge-case handling (empty inputs, boundary values, null/undefined, zero, negative numbers, empty collections)
+- Flag assumptions that are not validated or guarded
+- Detect logic errors in conditionals, loops, or state transitions
+- Look for off-by-one errors and boundary condition mistakes
+- Check for race conditions or shared-state issues where applicable
+
+**Robustness:**
+
+- Identify error conditions that are not handled
+- Detect resource-management issues (unclosed handles, leaked connections)
+- Flag missing input validation at trust boundaries
+- Check for fragile assumptions about external system behavior
+
+**Type Safety (where applicable):**
+
+- Flag use of `any` or untyped constructs when a precise type is feasible
+- Identify type assertions or casts that could panic or fail at runtime
+- Detect missing null checks when return types could be null or undefined
+
+## Issue Confidence Scoring
+
+Rate each issue from 0-100:
+
+- **0-25**: Cosmetic or style preference not tied to correctness
+- **26-50**: Minor readability improvement unlikely to cause bugs
+- **51-75**: Valid quality issue with low bug probability
+- **76-90**: Real quality problem that could cause maintenance issues or bugs
+- **91-100**: Clear defect — incorrect edge case handling, logic error, or serious maintainability hazard
+
+**Only report issues with confidence >= 80.** Skip nits, style preferences, and speculative concerns.
+
+## Output Format
+
+Return findings as a normalized list. For each high-confidence finding:
+
+```yaml
+- file: path/to/file
+  line: <head-file line number>
+  severity: critical | important | suggestion
+  source: code-quality-reviewer
+  message: <concise description of the issue and a concrete fix>
+```
+
+If no high-confidence issues exist, return an empty list and a one-line note confirming the code quality is good.
+
+## Tone
+
+Be specific and concrete. Prefer "the loop does not guard against an empty `files` list — add an early return or check before iterating" over "this could be improved." When the code is genuinely well-written, say so briefly. Analyze and report only; do not modify code.

.opencode/agents/code-reviewer.md

@@ -43,15 +43,18 @@ Rate each issue from 0-100:
 
 ## Output Format
 
-Start by listing what you're reviewing. For each high-confidence issue provide:
+Return findings as a normalized list. For each high-confidence issue (confidence >= 80):
 
-- Clear description and confidence score
-- File path and line number
-- Specific AGENTS.md rule or bug explanation
-- Concrete fix suggestion
+```yaml
+- file: path/to/file
+  line: <head-file line number>
+  severity: critical | important | suggestion
+  source: code-reviewer
+  message: <concise description of the issue, the AGENTS.md rule or bug explanation, and a concrete fix>
+```
 
-Group issues by severity (Critical: 90-100, Important: 80-89).
+Map confidence 91-100 to `critical`, 80-90 to `important`. Do not report findings below confidence 80.
 
-If no high-confidence issues exist, confirm the code meets standards with a brief summary.
+If no high-confidence issues exist, return an empty list and a one-line note confirming the code meets standards.
 
 Be thorough but filter aggressively - quality over quantity. Focus on issues that truly matter.

.opencode/agents/code-simplifier.md

@@ -2,6 +2,8 @@
 name: code-simplifier
 description: Simplifies recently written or modified code for clarity, consistency, and maintainability while preserving all functionality. Use after completing a coding task, fixing a bug, or optimizing performance — triggers on "simplify this code", "make this clearer", or "refine this implementation". Applies project best practices and focuses only on recently modified code unless instructed otherwise.
 mode: all
+permission:
+  edit: allow
 ---
 
 You are an expert code simplification specialist focused on enhancing code clarity, consistency, and maintainability while preserving exact functionality. Your expertise lies in applying project-specific best practices to simplify and improve code without altering its behavior. You prioritize readable, explicit code over overly compact solutions. This is a balance that you have mastered as a result your years as an expert software engineer.

.opencode/agents/comment-analyzer.md

@@ -55,28 +55,19 @@ When analyzing comments, you will:
    - Clear rationale for why comments should be removed
    - Alternative approaches for conveying the same information
 
-Your analysis output should be structured as:
+Your analysis output should be a normalized list. For each issue found:
 
-**Summary**: Brief overview of the comment analysis scope and findings
+```yaml
+- file: path/to/file
+  line: <head-file line number>
+  severity: critical | important | suggestion
+  source: comment-analyzer
+  message: <concise description of the comment issue and the recommended fix or removal rationale>
+```
 
-**Critical Issues**: Comments that are factually incorrect or highly misleading
+Map Critical Issues (factually incorrect or misleading) to `critical`, Improvement Opportunities (unclear, incomplete) to `suggestion`, Recommended Removals (no-value comments) to `suggestion`.
 
-- Location: [file:line]
-- Issue: [specific problem]
-- Suggestion: [recommended fix]
-
-**Improvement Opportunities**: Comments that could be enhanced
-
-- Location: [file:line]
-- Current state: [what's lacking]
-- Suggestion: [how to improve]
-
-**Recommended Removals**: Comments that add no value or create confusion
-
-- Location: [file:line]
-- Rationale: [why it should be removed]
-
-**Positive Findings**: Well-written comments that serve as good examples (if any)
+If no issues are found, return an empty list and a one-line note confirming comments are accurate and well-maintained.
 
 Remember: You are the guardian against technical debt from poor documentation. Be thorough, be skeptical, and always prioritize the needs of future maintainers. Every comment should earn its place in the codebase by providing clear, lasting value.