# Code Review Specialists Implementation Handoff

## Status

- Date: 2026-05-19
- Source type: discussion-to-implementation-doc
- Status: ready for implementation planning
- Intended next step: create and execute the sibling implementation plan.
- Recommended plan: docs/plans/code-review-specialists/code-review-specialists-plan.md
- Recommended execution state: docs/plans/code-review-specialists/code-review-specialists-execution-state.md

## Purpose

Agent-kit has strong review decision workflows, review evidence primitives, skill
governance, and issue/plan delivery boundaries. It does not yet have a general
code-review workflow that decomposes a diff into focused specialist passes before
a reviewer makes a merge, follow-up, or close decision.

This document records the agent-kit version of gstack's `/review` specialist
idea. The goal is to adopt the useful review decomposition pattern without
copying gstack's Claude-specific preamble, telemetry, auto-routing, auto-fix, or
fat workflow style.

## Confirmed Facts

- Upstream gstack `review/SKILL.md` has a "Review Army" section that selects
  specialists based on diff size and scope, dispatches selected specialists, and
  merges structured findings.
- Upstream gstack lists specialist files for `api-contract`, `data-migration`,
  `maintainability`, `performance`, `red-team`, `security`, and `testing` under
  `review/specialists/`.
- Upstream gstack uses JSON-object findings with fields such as severity,
  confidence, path, line, category, summary, fix, fingerprint, and specialist.
- Upstream gstack activates red-team review after the other specialists when the
  diff is larger than 200 lines or any specialist produced a critical finding.
- Upstream gstack's implementation also includes behavior agent-kit should not
  copy into this workflow: gstack config prompts, telemetry writes, automatic
  project routing changes, gstack-local learning state, and direct auto-fix
  handling inside the review workflow.
- Upstream gstack is MIT-licensed, so adapted prompt/checklist material can be
  used with attribution and license notice.
- Agent-kit's `issue-pr-review` is already the canonical path for main-agent PR
  review decisions in issue-driven loops.
- Agent-kit's `review-evidence` tool skill records normalized review findings
  and validation, but explicitly keeps review judgment in the workflow.
- Agent-kit's skill layout expects reusable markdown prompts/checklists under
  `references/` or `assets/`, not an arbitrary top-level `specialists/` folder.
- Agent-kit delegation policy is opt-in. A code-review specialist workflow must
  not treat the existence of the skill alone as blanket permission to spawn
  subagents.

## Decisions

- Add a new workflow skill named `code-review-specialists` under
  `skills/workflows/code-review/code-review-specialists/`.
- Store specialist checklists under
  `skills/workflows/code-review/code-review-specialists/references/specialists/`
  to match agent-kit skill layout rules.
- Include exactly these seven initial specialist checklists:
  `api-contract`, `data-migration`, `maintainability`, `performance`,
  `red-team`, `security`, and `testing`.
- Keep the workflow read-only in v1. It may produce findings, review reports,
  and optional evidence records, but it must not auto-edit product code.
- Preserve agent-kit delegation semantics:
  - Default mode: the main agent performs selected specialist passes as separate
    review lenses.
  - Delegated mode: use read-only reviewer subagents only when the user
    explicitly requests delegation or invokes an explicit delegation mode such as
    `parallel-first` or `orchestrator-first`.
- Add a small deterministic helper for scope detection and finding merge rather
  than relying on ad hoc parsing in prose.
- Normalize findings to an agent-kit schema:
  `severity`, `confidence`, `path`, `line`, `category`, `summary`, `evidence`,
  `recommendation`, `fingerprint`, `specialist`, and optional
  `test_suggestion`.
- Use agent-kit severity values: `critical`, `high`, `medium`, `low`, `info`.
  Upstream-style `CRITICAL` and `INFORMATIONAL` should be accepted only as input
  aliases and normalized.
- Activate red-team review when `diff_lines > 200` or any selected specialist
  produces a `critical` finding. Do not limit red-team activation to security
  findings.
- Do not adopt a numeric PR quality score in v1. Agent-kit should report
  blocking findings, confidence, coverage gaps, specialist dispatch stats, and
  evidence anchors instead of a false-precision score.
- Add attribution in a local reference file rather than embedding upstream
  provenance in every specialist prompt.

## Scope

- Create the `code-review-specialists` workflow skill.
- Adapt the seven specialist checklists into agent-kit wording and schema.
- Define specialist selection, execution modes, red-team gating, output schema,
  confidence gating, deduplication, and report format.
- Add deterministic helper coverage for diff scope detection and finding merge.
- Add catalog, README, and tooling-index discovery for the new workflow.
- Add optional references from `issue-pr-review` and shared review guidance so
  risky PR reviews can use specialist findings before a decision.
- Add focused tests for skill contract, layout, helper behavior, catalog wiring,
  and integration wording.

## Non-Scope

- Do not replace `issue-pr-review` decision handling.
- Do not auto-merge, auto-fix, close PRs, or post live PR comments from the new
  workflow.
- Do not create a new review evidence primitive; use existing `review-evidence`
  when durable evidence is needed.
- Do not introduce telemetry, gstack config files, proactive routing prompts, or
  cross-project learning state.
- Do not make subagent delegation mandatory for normal review use.
- Do not add browser QA behavior; browser-facing QA remains owned by
  `browser-qa`.
- Do not vendor upstream gstack wholesale.

## Implementation Boundaries

`code-review-specialists` should be a workflow skill. It owns review judgment,
specialist selection, and final synthesis. Deterministic helper scripts may own
only mechanical work:

- `scope`: inspect `git diff` paths and stats against a base ref and emit JSON
  scope signals such as `diff_lines`, `changed_files`, `scope_api`,
  `scope_auth`, `scope_backend`, `scope_frontend`, `scope_migrations`,
  `stack`, and `test_framework`.
- `merge-findings`: parse specialist JSONL outputs, normalize severity,
  validate required fields, compute fingerprints, deduplicate by fingerprint,
  apply confidence gates, report specialist stats, and emit machine-readable
  JSON plus a concise markdown summary.

The helper must not inspect secrets, call external services, mutate source code,
post comments, or decide whether a PR should merge.

## Requirements

- The skill must clearly describe when to use it:
  - explicit code-review specialist request,
  - risky PR/diff review,
  - large diff review,
  - pre-merge review where normal tests are insufficient,
  - issue/plan PR review where an additional specialist pass is warranted.
- The skill must clearly describe when not to use it:
  - tiny diffs,
  - ordinary implementation work,
  - pure formatting/doc-only changes unless requested,
  - CI repair loops where `gh-fix-ci` owns the workflow,
  - browser QA where `browser-qa` owns the workflow.
- Specialist selection should default to:
  - skip all specialists for `diff_lines < 50` unless forced by user request;
  - always consider `testing` and `maintainability` for larger diffs;
  - consider `security` for auth changes or backend changes over 100 diff lines;
  - consider `performance` for backend or frontend runtime changes;
  - consider `data-migration` for migration/schema/data-transform changes;
  - consider `api-contract` for route/controller/API/schema/openapi changes;
  - run `red-team` only after initial findings meet the activation rule.
- Forced specialist flags should be supported in prose contract, such as
  `--testing`, `--security`, `--performance`, `--data-migration`,
  `--api-contract`, `--maintainability`, `--red-team`, and
  `--all-specialists`.
- The workflow report must include selected/skipped specialists, merged
  findings, confidence notes, red-team status, validation commands reviewed, and
  explicit residual risk.
- Findings must cite concrete file paths or evidence anchors when available.
- `review-evidence` integration should be optional and evidence-focused, not a
  substitute for reviewer judgment.

## Acceptance Criteria

- `skills/workflows/code-review/code-review-specialists/SKILL.md` exists and
  passes skill contract validation.
- The new skill directory passes skill layout audit.
- The seven specialist prompts exist under `references/specialists/`.
- Upstream attribution and license guidance exists under the skill references.
- The helper script has tests for scope detection, JSONL parsing, severity
  normalization, confidence gating, deduplication, malformed input handling, and
  red-team activation.
- Catalog docs list `code-review-specialists` as a workflow, not a tool or
  automation.
- `issue-pr-review` guidance says the specialist workflow is an optional
  pre-decision input for risky or broad diffs, while `issue-pr-review` remains
  the decision path.
- Full skill governance and focused tests pass before reporting implementation
  complete.

## Validation Plan

Recommended focused commands:

```bash
scripts/check.sh --tests -- -k 'code_review_specialists or issue_pr_review or skill_usage'
skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh --file skills/workflows/code-review/code-review-specialists/SKILL.md
skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh --skill-dir skills/workflows/code-review/code-review-specialists
scripts/check.sh --entrypoint-ownership
scripts/check.sh --docs
scripts/check.sh --markdown
```

Before delivery, run:

```bash
scripts/check.sh --all
```

## Risks And Guardrails

- Specialist prompts can increase review noise. Mitigate with scope gating,
  confidence gates, deduplication, and concise report requirements.
- Blindly copying upstream prompt text can import gstack-specific assumptions.
  Mitigate by adapting language to agent-kit and preserving only checklist
  categories that are framework-agnostic enough for general code review.
- Subagent use can violate agent-kit delegation policy if made automatic.
  Mitigate by documenting default single-agent mode and making delegated mode
  opt-in.
- A merge helper can become a hidden decision engine. Keep it limited to schema,
  sorting, deduplication, and summary mechanics.
- Review findings without evidence anchors can become speculation. Require
  confidence and evidence fields or mark the finding as unverified.
- A broad code-review workflow can overlap with `issue-pr-review`,
  `review-evidence`, `browser-qa`, and CI workflows. Keep each boundary explicit.

## Execution

- Recommended next artifact:
  `docs/plans/code-review-specialists/code-review-specialists-plan.md`
- Recommended execution-state path:
  `docs/plans/code-review-specialists/code-review-specialists-execution-state.md`
- Current execution status: ready for implementation planning.

## Retention Intent

This document is temporary implementation source material for the plan bundle.
After implementation lands, durable guidance should live in the new skill,
specialist reference files, catalog docs, and affected review workflow docs. The
plan-source folder can be cleaned up through the normal plan cleanup flow when
it is no longer useful.

## Read First References

- Upstream gstack review workflow:
  <https://github.com/garrytan/gstack/blob/main/review/SKILL.md>
- Upstream gstack specialist directory:
  <https://github.com/garrytan/gstack/tree/main/review/specialists>
- Upstream gstack license:
  <https://github.com/garrytan/gstack/blob/main/LICENSE>
- Local issue review workflow:
  `skills/workflows/issue/issue-pr-review/SKILL.md`
- Local review evidence tool:
  `skills/tools/workflow-evidence/review-evidence/SKILL.md`
- Local skill review checklist:
  `docs/runbooks/skills/SKILL_REVIEW_CHECKLIST.md`
