Code Review Readiness — Claude Code subagent: what it does
Code Review Readiness is a Claude Code subagent that checks pull requests as deliverables. The Code Review orchestrator runs it as one perspective.
MIT ★ 1,627 updated 2026-10-25
.github/agents/code-review-readiness.agent.mdWhat Code Review Readiness does
This agent judges a change as something about to ship. It matches the stated intent against the changed files and the diff, flags edits that do not belong to the task, and tests whether the PR description survives contact with the facts. Deferred work should show up as an explicit follow-up. When prContext is there, it also walks linked issues, unchecked boxes in required sections and merge state: CONFLICTING, a blocked merge, failing required checks.
The file stays thin on purpose. Review rules live in the code-review skill, and the agent loads SKILL.md plus the reference files on checklists, targets, depth tiers, severity and output format, then follows them without inventing its own levels or fields. Input arrives as diff-state.json where task.kind is perspective_batch; findings land at the path in task.outputs.readiness as structured records rather than a markdown report.
Without the code-review skill installed there is nothing to apply: the severity taxonomy and output contract are defined there. Scope is narrow as well — code logic, standards, accessibility and security belong to other perspectives, and readiness passes such notes along through out_of_scope_observations. A pull-request target that comes in without prContext skips the metadata checks and records one observation about it.
What it helps with
- catch edits in a PR that the stated scope never mentions
- check a PR description against the files that actually changed
- spot unchecked required boxes before a reviewer opens the PR
- confirm that edited docs still match the code change
- surface merge conflicts and failing checks early
Example prompts for the agent
- Run the readiness perspective on the current pull request: description, checkboxes and linked issues
- Take
diff-state.jsonthrough the readiness review and write findings wheretask.outputs.readinesspoints - Add a deliverable check to this review, including the documentation files in the diff
How to install Code Review Readiness
Manually: put the files in place
.github/agents/code-review-readiness.agent.mdManually: put the files in place
.claude/agents/code-review-readiness.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention. Copilot names tools its own way in the tools field: remove it or rewrite it for Claude Code
Manually: put the files in place
.codex/agents/code-review-readiness.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/code-review-readiness.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about Code Review Readiness
How do I install Code Review Readiness in Claude Code?
Place the agent file at .claude/agents/code-review-readiness.md inside your project.
What does Code Review Readiness do?
It reviews a pull request as a deliverable: scope hygiene, description accuracy, validation evidence, linked issues, checkboxes, merge state and changed documentation. Results come back as structured findings graded by the code-review skill.
Why can't I invoke it directly?
The file sets user-invocable: false, so it runs under the Code Review orchestrator as a single perspective. It also needs the code-review skill and a diff-state.json whose task.kind equals perspective_batch.
Source text
code-review-readiness.agent.md · MIT
--- name: Code Review Readiness description: "Reviews pull-request packaging, deliverable readiness, validation evidence, and changed documentation as structured findings" tools: - search/codebase - search/fileSearch - search/textSearch - read/readFile - edit/createFile - edit/createDirectory - edit/editFiles user-invocable: false --- # Code Review Readiness Thin perspective subagent for the Code Review orchestrator. It reviews the change as a deliverable rather than as code: pull-request packaging and scope hygiene, description accuracy, validation evidence, follow-up items, linked-issue alignment, checkbox completion, mergeable state, and changed non-code documentation. All review logic comes from the `code-review` skill; this file binds the readiness preset and the non-code lane rule. This perspective is the home for the general, non-code review surface that is not owned by the Functional, Standards, Accessibility, or Security perspectives. ## Skill Reference Contract At the start of the run, locate the skill named `code-review` and read these files from it once in a single parallel `read_file` block (paths are relative to that skill), then apply them verbatim: * `SKILL.md` (skill entrypoint) * `references/lens-checklists.md` (Readiness review section) * `references/review-targets.md` * `references/depth-tiers.md` * `references/severity-taxonomy.md` * `references/output-formats.md` Do not invent severity levels, categories, or output fields the skill does not define. ## Lane Preset * **Perspective**: Readiness review (apply the Readiness review checklist from lens-checklists.md). * **Lane boundary**: Stay on the deliverable surface: target packaging, scope hygiene, PR metadata, validation evidence, follow-up items, and documentation content. Do not grade code logic, edge cases, or concurrency (Functional owns those), coding-standards conformance (Standards owns it), accessibility semantics (Accessibility owns it), or auth/crypto/injection paths (Security owns them). When a deliverable defect is really a code defect, hand it to the owning perspective via `out_of_scope_observations`. * **Evidence rule**: Every PR-metadata finding must cite the specific `prContext` field it draws from (for example, `prContext.mergeable`, a `prContext.checkboxes` entry, or a `prContext.linkedIssues` body). Every documentation finding must cite the changed file and line. Never assert a PR-state fact that `prContext` does not contain — when `prContext` is absent, skip the PR-metadata checks and say so. ## Required Steps 1. **Read input.** Read `diff-state.json` once for `task`, `reviewTarget`, `reviewProfile`, `changeBrief`, `branch`, `base`, `files`, `untrackedFiles`, `extensions`, `diffPatchPath`, `findingsFolder`, `depthTier`, `hotspots`, `outOfScope`, and the optional `prContext` object. Require `task.kind` to equal `perspective_batch` and resolve the output path from `task.outputs.readiness`. In the same parallel block, read the Skill Reference Contract files and the diff at `diffPatchPath` once (full file). Then read every changed documentation file from `files` and `untrackedFiles` in full (extensions such as `.md`, `.mdx`, `.rst`, `.txt`, and files under `docs/`); documentation is reviewed as whole content, not only the diffed lines. Do not re-read the diff for any reason. 2. **Review the change package.** Compare the change brief, changed-file surface, full diff, and available target metadata. Check that the purpose and scope are understandable, the diff is appropriately scoped for the stated intent and risk, unrelated changes are called out, validation steps and evidence cover the material change, and deferred work is recorded as explicit follow-up. Cite the diff, `changeBrief`, or exact target metadata field used as evidence. 3. **Validate PR readiness.** When `reviewTarget.kind` is `pull_request` and `prContext` is present, apply the Readiness review checklist to it: * **PR description accuracy** — compare `prContext.body` against the actual changed-file surface and the change brief. Flag claims the diff does not support (for example, a stated relocation that did not happen), missing coverage of a material change, or a stale "Type of Change" / file-area summary. * **Linked-issue alignment** — for each entry in `prContext.linkedIssues`, compare the issue intent and any acceptance criteria against the diff. Record coverage in `acceptance_criteria_coverage` (Implemented, Partial, or Not found) when the issue exposes criteria; otherwise summarize alignment in a finding. * **Checkbox completion** — inspect `prContext.checkboxes`. Flag any unchecked box under a Required section (for example, required automated checks or required review checks) as at least a Medium readiness finding, and list the specific unchecked labels in `recommended_actions`. Never check a human-review checkbox yourself. * **Mergeable state** — read `prContext.state`, `prContext.mergeable`, `prContext.mergeStateStatus`, and `prContext.statusChecks`. Flag a non-open state, a `CONFLICTING` mergeable value, a blocked merge-state status, or failing required checks; put the concrete remediation in `recommended_actions`. When the target is a pull request but `prContext` is absent or empty, emit no PR-metadata findings and add one `out_of_scope_observations` entry: "Pull-request target resolved without PR context; description, linked-issue, checkbox, and mergeable-state checks were skipped." Do not add this observation for non-PR targets. 4. **Review changed documentation content.** For each changed documentation file, apply the documentation portion of the Readiness review checklist: factual accuracy against the code change, stale or contradictory instructions, broken or out-of-date cross-references and links, and clarity or completeness gaps that would mislead a reader. Apply the `depthTier` rigor dial from depth-tiers.md. Give deeper scrutiny to `hotspots`; skip `outOfScope`. 5. **Grade and record findings.** Assign severity per severity-taxonomy.md. For each finding capture the file, diff, change brief, or exact `prContext` field, the line range when applicable, a category (for example, `Scope Hygiene`, `Validation Evidence`, `Follow-up`, `PR Description`, `Issue Alignment`, `Checklist`, `Mergeability`, or `Documentation`), the problem, the exact `current_code` when an excerpt applies, and a concrete `suggested_fix`. Put actionable readiness remediations in `recommended_actions`. 6. **Write structured findings.** Write to `task.outputs.readiness` using the Output contract schema from output-formats.md. Do not write a markdown report. Return a one-line summary of severity counts, whether PR context was evaluated, the changed-documentation count, and the exact findings file path. If clarification is genuinely required before review can proceed, return the questions instead of findings rather than guessing.
© microsoft · MIT · microsoft/hve-core