# Plan: Code Review Specialists

## Overview

Add an agent-kit-native `code-review-specialists` workflow that decomposes risky
or broad diffs into focused review lenses adapted from gstack's `/review`
specialists. The workflow stays read-only, preserves `issue-pr-review` as the
PR decision path, and uses deterministic helpers only for scope detection and
finding merge mechanics. Specialist prompts live under the skill's
`references/` tree, while durable findings can optionally flow into existing
`review-evidence` records.

## Read First

- Primary source: `docs/plans/code-review-specialists/code-review-specialists-discussion-source.md`
- Source type: `discussion-to-implementation-doc`
- Execution state: `docs/plans/code-review-specialists/code-review-specialists-execution-state.md`
- Open questions carried into execution: none

## Scope

- In scope: a new `code-review-specialists` workflow skill, seven specialist
  reference prompts, upstream attribution, deterministic scope/finding helper
  scripts, focused tests, catalog docs, and optional integration guidance for
  `issue-pr-review`.
- Out of scope: auto-fixing code, replacing `issue-pr-review`, creating a new
  review evidence primitive, mandatory subagent delegation, telemetry,
  gstack-local config/learning state, browser QA, and wholesale vendoring of
  upstream gstack.

## Assumptions

1. The initial public skill should live at
   `skills/workflows/code-review/code-review-specialists/`.
2. `references/specialists/` is the correct location for specialist markdown
   prompts because top-level arbitrary skill subdirectories are not allowed.
3. A small helper script is acceptable because it handles deterministic parsing
   and merging only; review judgment remains in the workflow.
4. The first implementation should be read-only. Fixes stay in normal
   implementation or review-follow-up workflows.
5. User invocation of this skill does not automatically grant subagent
   delegation. Delegated specialist execution requires an explicit delegation
   mode or user request.

## Sprint 1: Workflow Contract And Specialist References

**Goal**: Add the new workflow skill and specialist reference files with
agent-kit-native boundaries and upstream attribution.
**Demo/Validation**:

- Command(s): `scripts/check.sh --tests -- -k code_review_specialists`,
  `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`
- Verify: the skill contract validates, the skill layout is allowed, and all
  seven specialist references are present.

**PR grouping intent**: group
**Execution Profile**: parallel-x2

### Task 1.1: Create the workflow skill skeleton

- **Location**:
  - `skills/workflows/code-review/code-review-specialists/SKILL.md`
  - `skills/workflows/code-review/code-review-specialists/tests/test_workflows_code_review_specialists.py`
- **Description**: Create the script-backed workflow skill contract. Define
  prerequisites, inputs, outputs, failure modes, read-only behavior, execution
  modes, and the relationship to `issue-pr-review`, `review-evidence`, and
  delegation modes.
- **Dependencies**:
  - none
- **Complexity**: 4
- **Acceptance criteria**:
  - The skill contract follows the canonical heading order.
  - The skill says it is read-only and does not auto-fix, merge, close, or post
    live PR comments.
  - The skill documents default single-agent mode and opt-in delegated mode.
  - The skill defines when to use and when not to use specialist review.
  - Tests assert the boundary with `issue-pr-review` and delegation policy.
- **Validation**:
  - `scripts/check.sh --tests -- skills/workflows/code-review/code-review-specialists/tests/test_workflows_code_review_specialists.py`
  - `skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh --file skills/workflows/code-review/code-review-specialists/SKILL.md`

### Task 1.2: Add adapted specialist checklists

- **Location**:
  - `skills/workflows/code-review/code-review-specialists/references/specialists/api-contract.md`
  - `skills/workflows/code-review/code-review-specialists/references/specialists/data-migration.md`
  - `skills/workflows/code-review/code-review-specialists/references/specialists/maintainability.md`
  - `skills/workflows/code-review/code-review-specialists/references/specialists/performance.md`
  - `skills/workflows/code-review/code-review-specialists/references/specialists/red-team.md`
  - `skills/workflows/code-review/code-review-specialists/references/specialists/security.md`
  - `skills/workflows/code-review/code-review-specialists/references/specialists/testing.md`
- **Description**: Adapt the seven gstack specialist checklists to agent-kit
  language, schema, and evidence expectations. Keep the categories concise and
  framework-agnostic; remove gstack path assumptions and Claude-specific
  dispatch instructions.
- **Dependencies**:
  - Task 1.1
- **Complexity**: 5
- **Acceptance criteria**:
  - All seven specialist files exist under `references/specialists/`.
  - Each file names its activation scope, required output shape, evidence
    expectations, and "no findings" behavior.
  - Findings use agent-kit severity values:
    `critical|high|medium|low|info`.
  - `red-team` explicitly says it runs after other selected specialists and
    receives their merged findings.
  - No specialist prompt includes gstack home paths, telemetry, auto-routing, or
    auto-fix instructions.
- **Validation**:
  - `scripts/check.sh --tests -- -k code_review_specialists`
  - `scripts/check.sh --markdown`

### Task 1.3: Add upstream attribution and shared review contract references

- **Location**:
  - `skills/workflows/code-review/code-review-specialists/references/UPSTREAM_GSTACK.md`
  - `skills/workflows/code-review/code-review-specialists/references/SPECIALIST_REVIEW_CONTRACT.md`
  - `skills/workflows/code-review/code-review-specialists/tests/test_workflows_code_review_specialists.py`
- **Description**: Add one attribution file for the upstream gstack source and
  license, plus a shared contract that defines the normalized finding schema,
  confidence semantics, forced specialist flags, confidence gates, and report
  sections.
- **Dependencies**:
  - Task 1.1
  - Task 1.2
- **Complexity**: 3
- **Acceptance criteria**:
  - Attribution links upstream gstack review, specialist directory, and license.
  - The shared contract documents normalized schema fields and accepted severity
    aliases.
  - The shared contract states that numeric PR quality scoring is not adopted in
    v1.
  - Tests assert attribution and schema guidance are present.
- **Validation**:
  - `scripts/check.sh --tests -- -k code_review_specialists`
  - `scripts/check.sh --markdown`

## Sprint 2: Scope Detection And Finding Merge Helpers

**Goal**: Make specialist selection and finding synthesis deterministic enough
to be testable without turning the helper into a review decision engine.
**Demo/Validation**:

- Command(s): `scripts/check.sh --tests -- -k code_review_specialists`,
  `scripts/check.sh --entrypoint-ownership`
- Verify: helper commands emit stable scope JSON, normalize/merge findings, and
  stay owned by skill tests.

**PR grouping intent**: group
**Execution Profile**: parallel-x2

### Task 2.1: Implement scope detection helper

- **Location**:
  - `skills/workflows/code-review/code-review-specialists/scripts/review_specialists.py`
  - `skills/workflows/code-review/code-review-specialists/tests/test_workflows_code_review_specialists.py`
  - `tests/script_specs/skills/workflows/code-review/code-review-specialists/scripts/review_specialists.py.json`
- **Description**: Add a deterministic `scope` subcommand that inspects a diff
  against a base ref and emits JSON scope signals for specialist selection.
- **Dependencies**:
  - Task 1.1
- **Complexity**: 5
- **Acceptance criteria**:
  - The helper supports `scope --base <ref>` and returns JSON.
  - Output includes `diff_lines`, `changed_files`, `scope_api`,
    `scope_auth`, `scope_backend`, `scope_frontend`, `scope_migrations`,
    `stack`, `test_framework`, and a suggested specialist list.
  - The helper uses git diff metadata and path patterns only; it does not read
    secrets or call external services.
  - Tests cover backend, frontend, auth, API, migration, test-only, and docs-only
    diffs.
- **Validation**:
  - `scripts/check.sh --tests -- -k code_review_specialists`
  - `scripts/check.sh --entrypoint-ownership`

### Task 2.2: Implement findings merge helper

- **Location**:
  - `skills/workflows/code-review/code-review-specialists/scripts/review_specialists.py`
  - `skills/workflows/code-review/code-review-specialists/tests/fixtures/merge_findings_valid.jsonl`
  - `skills/workflows/code-review/code-review-specialists/tests/fixtures/merge_findings_malformed.jsonl`
  - `skills/workflows/code-review/code-review-specialists/tests/fixtures/merge_findings_duplicates.jsonl`
  - `skills/workflows/code-review/code-review-specialists/tests/test_workflows_code_review_specialists.py`
- **Description**: Add a deterministic `merge-findings` subcommand that parses
  specialist JSONL outputs, normalizes severity, validates required fields,
  computes fingerprints, deduplicates, applies confidence gates, and emits JSON
  plus markdown summary output.
- **Dependencies**:
  - Task 1.3
  - Task 2.1
- **Complexity**: 6
- **Acceptance criteria**:
  - The helper accepts one or more JSONL files and rejects malformed findings
    with actionable line-number errors.
  - `CRITICAL` and `INFORMATIONAL` input aliases normalize to agent-kit
    severities.
  - Duplicate fingerprints keep the highest-confidence finding and record
    confirming specialists.
  - Confidence below the configured display threshold is suppressed or moved to
    an appendix in the emitted summary.
  - Output includes per-specialist dispatch stats and merged finding counts.
  - The helper does not produce a merge/follow-up decision.
- **Validation**:
  - `scripts/check.sh --tests -- -k code_review_specialists`

### Task 2.3: Wire helper usage into the workflow

- **Location**:
  - `skills/workflows/code-review/code-review-specialists/SKILL.md`
  - `skills/workflows/code-review/code-review-specialists/references/SPECIALIST_REVIEW_CONTRACT.md`
  - `skills/workflows/code-review/code-review-specialists/tests/test_workflows_code_review_specialists.py`
- **Description**: Document the operational flow: establish base ref, run scope
  detection, select specialists, run selected specialist passes, merge findings,
  conditionally run red-team, merge again, then write the final review report.
- **Dependencies**:
  - Task 2.1
  - Task 2.2
- **Complexity**: 4
- **Acceptance criteria**:
  - The skill documents skip behavior for `diff_lines < 50` unless forced.
  - The skill documents force flags for each specialist and all-specialists.
  - Red-team activation is `diff_lines > 200` or any `critical` finding from
    selected specialists.
  - The skill tells reviewers to cite concrete file/evidence anchors and mark
    unverifiable claims as residual risk.
  - Tests fail if the skill reintroduces auto-fix or mandatory delegation.
- **Validation**:
  - `scripts/check.sh --tests -- -k code_review_specialists`

## Sprint 3: Evidence, Reporting, And Workflow Integration

**Goal**: Make specialist findings useful inside agent-kit review workflows
without replacing existing review decision paths.
**Demo/Validation**:

- Command(s): `scripts/check.sh --tests -- -k 'code_review_specialists or issue_pr_review or skill_usage'`,
  `scripts/check.sh --docs`
- Verify: reports can feed `review-evidence`, and `issue-pr-review` remains the
  decision workflow.

**PR grouping intent**: group
**Execution Profile**: parallel-x2

### Task 3.1: Add the specialist review report template

- **Location**:
  - `skills/workflows/code-review/code-review-specialists/references/SPECIALIST_REVIEW_REPORT_TEMPLATE.md`
  - `skills/workflows/code-review/code-review-specialists/SKILL.md`
  - `skills/workflows/code-review/code-review-specialists/tests/test_workflows_code_review_specialists.py`
- **Description**: Add a concise report template for final synthesis. The
  template should summarize selected/skipped specialists, merged findings,
  red-team status, reviewed validation evidence, recommended follow-up path, and
  residual risk.
- **Dependencies**:
  - Task 2.3
- **Complexity**: 3
- **Acceptance criteria**:
  - The template includes sections for Scope, Specialist Dispatch, Findings,
    Red Team, Evidence Reviewed, Residual Risk, and Recommended Next Step.
  - The template does not include numeric PR quality scoring.
  - The template distinguishes review findings from merge decisions.
  - The skill points to the template as the canonical report shape.
- **Validation**:
  - `scripts/check.sh --tests -- -k code_review_specialists`
  - `scripts/check.sh --markdown`

### Task 3.2: Document optional review-evidence integration

- **Location**:
  - `skills/workflows/code-review/code-review-specialists/SKILL.md`
  - `skills/workflows/code-review/code-review-specialists/references/SPECIALIST_REVIEW_CONTRACT.md`
  - `skills/tools/workflow-evidence/review-evidence/SKILL.md`
  - `skills/tools/workflow-evidence/review-evidence/tests/test_tools_devex_review_evidence.py`
- **Description**: Explain how durable findings can be recorded with the
  existing `review-evidence` primitive when a review needs retained evidence.
  Keep the CLI as an evidence record, not a reviewer.
- **Dependencies**:
  - Task 3.1
- **Complexity**: 3
- **Acceptance criteria**:
  - The workflow explains when to create a `review-evidence` record.
  - The workflow maps specialist severities to current `review-evidence`
    `high|medium|low` recording where needed.
  - The review-evidence docs mention specialist review only as an optional
    source of findings.
  - Tests preserve the statement that `review-evidence` does not replace review
    judgment.
- **Validation**:
  - `scripts/check.sh --tests -- -k 'code_review_specialists or review_evidence'`

### Task 3.3: Integrate as an optional input to issue PR review

- **Location**:
  - `skills/workflows/issue/issue-pr-review/SKILL.md`
  - `skills/workflows/issue/_shared/references/MAIN_AGENT_REVIEW_RUBRIC.md`
  - `skills/workflows/issue/issue-pr-review/tests/test_workflows_issue_issue_pr_review.py`
  - `skills/workflows/code-review/code-review-specialists/tests/test_workflows_code_review_specialists.py`
- **Description**: Add guidance that `code-review-specialists` can be run before
  an `issue-pr-review` decision for broad, high-risk, security-sensitive,
  migration-heavy, or API-contract-heavy diffs. Preserve `issue-pr-review` as
  the action path for request-followup, merge, and close-pr decisions.
- **Dependencies**:
  - Task 3.1
  - Task 3.2
- **Complexity**: 3
- **Acceptance criteria**:
  - `issue-pr-review` does not become dependent on specialist review for every
    PR.
  - The shared rubric treats specialist findings as supplemental evidence, not a
    decision shortcut.
  - Tests fail if wording implies specialist review can merge or close PRs.
  - The flow explains how to carry findings into decision-scoped review
    evidence.
- **Validation**:
  - `scripts/check.sh --tests -- -k 'code_review_specialists or issue_pr_review'`

### Task 3.4: Update catalog and tooling docs

- **Location**:
  - `README.md`
  - `skills/README.md`
  - `docs/runbooks/skills/TOOLING_INDEX_V2.md`
  - `docs/runbooks/skills/SKILL_USAGE_RECORDING_V1.md`
- **Description**: Add the workflow to public discovery surfaces and document
  the boundary between code-review specialists, issue review decisions, and
  review evidence records.
- **Dependencies**:
  - Task 1.1
  - Task 3.1
  - Task 3.2
  - Task 3.3
- **Complexity**: 3
- **Acceptance criteria**:
  - README lists `code-review-specialists` under workflow skills.
  - Skills README places the skill under a Code Review or Review workflow area.
  - Tooling index lists only maintained helper entrypoints and does not imply
    candidate future primitives are implemented.
  - Skill usage docs mention specialist review records only when retained
    workflow evidence is required.
- **Validation**:
  - `scripts/check.sh --docs`
  - `scripts/check.sh --markdown`

## Sprint 4: Regression Coverage And Delivery Readiness

**Goal**: Close the implementation with repo-wide validation, fixture coverage,
and cleanup of any plan-only assumptions.
**Demo/Validation**:

- Command(s): `scripts/check.sh --all`
- Verify: all contracts, skill layout, docs, markdown, tests, script ownership,
  and smoke checks required by the repo pass.

**PR grouping intent**: per-sprint
**Execution Profile**: serial

### Task 4.1: Add fixture coverage for realistic specialist outputs

- **Location**:
  - `skills/workflows/code-review/code-review-specialists/tests/fixtures/no_findings.txt`
  - `skills/workflows/code-review/code-review-specialists/tests/fixtures/merge_findings_valid.jsonl`
  - `skills/workflows/code-review/code-review-specialists/tests/fixtures/merge_findings_malformed.jsonl`
  - `skills/workflows/code-review/code-review-specialists/tests/fixtures/merge_findings_duplicates.jsonl`
  - `skills/workflows/code-review/code-review-specialists/tests/fixtures/merge_findings_low_confidence.jsonl`
  - `skills/workflows/code-review/code-review-specialists/tests/fixtures/merge_findings_red_team.jsonl`
  - `skills/workflows/code-review/code-review-specialists/tests/test_workflows_code_review_specialists.py`
- **Description**: Add fixture files representing no-findings output,
  duplicate findings, low-confidence findings, malformed JSONL, mixed upstream
  severity aliases, and red-team additions.
- **Dependencies**:
  - Task 2.2
  - Task 2.3
- **Complexity**: 3
- **Acceptance criteria**:
  - Fixtures cover success and failure paths.
  - Tests assert line-numbered errors for malformed JSONL.
  - Tests assert red-team findings can be merged with normal specialist
    findings.
  - Tests assert suppressed low-confidence findings do not appear in the main
    summary.
- **Validation**:
  - `scripts/check.sh --tests -- -k code_review_specialists`

### Task 4.2: Run governance and repo checks

- **Location**:
  - `skills/workflows/code-review/code-review-specialists/SKILL.md`
  - `skills/workflows/code-review/code-review-specialists/scripts/review_specialists.py`
  - `skills/workflows/code-review/code-review-specialists/tests/test_workflows_code_review_specialists.py`
  - `tests/script_specs/skills/workflows/code-review/code-review-specialists/scripts/review_specialists.py.json`
  - `README.md`
  - `skills/README.md`
  - `docs/runbooks/skills/TOOLING_INDEX_V2.md`
  - `docs/runbooks/skills/SKILL_USAGE_RECORDING_V1.md`
- **Description**: Run the repo's focused and broad validation commands, fix
  contract/layout/docs drift, and ensure the helper entrypoint is owned by
  tests and script specs.
- **Dependencies**:
  - Task 1.1
  - Task 1.2
  - Task 1.3
  - Task 2.1
  - Task 2.2
  - Task 2.3
  - Task 3.1
  - Task 3.2
  - Task 3.3
  - Task 3.4
  - Task 4.1
- **Complexity**: 3
- **Acceptance criteria**:
  - `validate_skill_contracts.sh` passes for the new skill.
  - `audit-skill-layout.sh` passes for the new skill.
  - `scripts/check.sh --entrypoint-ownership` passes.
  - `scripts/check.sh --docs` and `scripts/check.sh --markdown` pass.
  - `scripts/check.sh --all` passes or any residual failure is unrelated and
    explicitly evidenced.
- **Validation**:
  - `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`
  - `scripts/check.sh --all`

### Task 4.3: Prepare implementation handoff and cleanup notes

- **Location**:
  - `docs/plans/code-review-specialists/code-review-specialists-execution-state.md`
  - `docs/plans/code-review-specialists/code-review-specialists-plan.md`
- **Description**: Record final execution status, validation results, remaining
  risks, and cleanup intent so the plan bundle can be retired or promoted after
  implementation.
- **Dependencies**:
  - Task 4.2
- **Complexity**: 2
- **Acceptance criteria**:
  - Execution state records completed tasks, validation commands, and any
    residual known issues.
  - The plan-source document remains linked under `Read First`.
  - Cleanup or promotion recommendation is explicit.
- **Validation**:
  - `plan-tooling validate --file docs/plans/code-review-specialists/code-review-specialists-plan.md`

## Testing Strategy

- Unit: focused pytest coverage for the new workflow skill docs and helper
  behavior under
  `skills/workflows/code-review/code-review-specialists/tests/`.
- Integration: skill-governance contract/layout validation, entrypoint
  ownership checks, script smoke spec checks, and docs/catalog tests.
- E2E/manual: no browser or live PR action is required for this plan. A manual
  dry-run review on a representative local diff can be used as additional
  validation, but it should not replace automated helper and docs tests.

## Risks & gotchas

- Specialist review can become noisy if every specialist runs on every diff.
  Keep diff-size, scope, and forced-flag gating.
- Specialist prompts can drift into provider-specific instructions. Keep the
  contract model-agnostic and use agent-kit delegation wording.
- Mandatory subagents would conflict with agent-kit delegation policy. Keep
  default single-agent review and make delegated execution explicit.
- The helper script must not become a hidden review or merge decision engine.
  Keep it limited to scope detection, schema validation, normalization,
  deduplication, and formatting.
- Severity mapping can lose detail when sending findings to current
  `review-evidence` commands. Preserve normalized severity in the report and
  document any `high|medium|low` mapping used for evidence records.
- Upstream checklist text may import assumptions that do not hold in every
  stack. Adapt language and require evidence anchors instead of generic pattern
  accusations.
- This repo currently has unrelated dirty work. Implementation should keep this
  plan's file set isolated from existing changes unless the user explicitly
  asks to bundle them.

## Rollback plan

- Remove `skills/workflows/code-review/code-review-specialists/`.
- Revert catalog references in `README.md`, `skills/README.md`, and tooling docs.
- Revert optional guidance added to `issue-pr-review` and shared review rubric.
- Remove related test fixtures and script specs.
- Rerun `scripts/check.sh --docs`, `scripts/check.sh --markdown`, and
  `scripts/check.sh --all` to confirm the repo returns to its prior workflow
  surface.
