Kiro Code Review: Turn Specs Into a Merge Gate

How should Kiro code review fit into a merge gate?

Use Kiro specs to define intended behavior, steering to supply repository rules, and hooks or headless review for fast feedback. Then bind accepted findings, focused tests, required CI, and an independent review verdict to the pull request's exact current head. Any later commit makes the earlier pass stale.

As of September 3, 2026, Kiro spans more of the development lifecycle than a comment-only reviewer. Its current documentation covers structured specs, requirement analysis, steering files, agent hooks, custom agents, headless CI execution, and a web agent that can create branches and pull requests. That range is useful because the agent can retain the reason for a change while it implements and revises the code.

It also creates a review problem: intent, authorship, feedback, and repair can all happen in one product. A clean Kiro response cannot by itself show that the repository tested the current revision, that the spec was complete, or that every blocking finding was closed with evidence. The generalAI code review workflow for GitHubseparates intent, execution, evidence, verdict, and merge state. This guide adds a Kiro-specific link between the spec artifacts and that exact-head verdict.

What does Kiro code review cover?

“Kiro code review” can mean three different jobs. You can ask an interactive or custom Kiro agent to inspect a change. You can trigger post-processing with an agent hook. You can also run Kiro CLI in headless mode inside CI. These surfaces share context and models, but they do not automatically share one enforceable result contract.

Kiro'scustom-agent examplesinclude a code-review agent with read and shell tools, explicit allow and deny rules, repository resources, and a hook that collects changed files. Itsheadless-mode documentationshows a non-interactive GitHub Actions review and supports JSON Lines run events on current engines. That makes Kiro usable as a review worker in a pipeline.

A review worker is not yet a merge gate. A repository gate needs a stable pass, needs-changes, and operational-error contract; a reviewed commit identifier; a rule for stale results; and a finding lifecycle that survives comments moving or being resolved. If the job prints persuasive prose but does not identify the code it evaluated, the repository cannot safely require that prose as current evidence.

Kiro's web documentation is explicit that review and merge stay in the normal repository workflow. The in-session review panel lets you inspect changed files and copy commit SHAs, while comments, approval, and merge happen in GitHub. That boundary is a good starting point. The next step is to make the evidence crossing it inspectable.

Use a spec-to-verdict receipt for Kiro code review

The missing artifact in most Kiro review guides is a spec-to-verdict receipt: a compact record connecting the accepted specification to the exact code, review obligations, tests, and repository verdict. Kiro's spec files tell you what the agent intended to build. GitHub and CI tell you what revision was evaluated. The receipt makes the transition between them explicit.

This is an operating framework, not a Kiro feature claim. You can keep it in a PR description, a machine-readable review artifact, or a bot-owned summary. The storage matters less than the invariant: every value must refer to a stable revision, and every mutation must produce a new receipt state.

spec_to_verdict:
  spec_id: "checkout-tax-fix"
  requirements_ref: "<commit-or-content-digest>"
  design_ref: "<commit-or-content-digest>"
  task_ids: ["2.1", "2.2", "2.3"]
  authored_head: "<40-character PR head>"
  review_policy_ref: "<commit containing review rules>"
  reviewed_head: "<40-character reviewed head>"
  obligations:
    open: []
    closed_with_evidence: ["finding-authz-01"]
  focused_tests:
    - requirement: "REQ-3.2"
      command: "<repository-owned test command>"
      tested_head: "<40-character tested head>"
  verdict:
    status: "passed"
    head: "<40-character current head>"

The receipt catches two failures that ordinary review comments miss. First, code can match an incomplete spec. A reviewer should challenge the requirement before congratulating the implementation. Second, a fix can close a comment while invalidating the old tests and review. The receipt refuses to carry the old pass across the new commit.

1. Choose the Kiro spec workflow by review risk

Start before the code exists. KiroQuick Spec generatesrequirements.md, design.md, and tasks.md in one pass, without approval gates between those phases. Kiro recommends it for well-understood work and rapid prototypes. Its standard Feature Spec workflow is the safer default when requirements or design need iteration and review gates add value.

Choose by the cost of a wrong assumption, not by the size of the diff. A three-line authorization change can deserve more specification review than a large mechanical rename. Use the standard workflow for security boundaries, billing behavior, migrations, compatibility promises, concurrency, or any change whose missing edge case would be expensive to discover after merge.

1. Name the user-visible behavior and the behavior that must remain unchanged.
2. List trust boundaries, failure modes, and compatibility constraints.
3. Choose Requirements-First when behavior drives the design.
4. Choose Design-First when an architecture constraint drives feasible behavior.
5. Use Quick Spec only when skipped artifact approvals are an accepted tradeoff.

Done means the pull request can point to a stable spec and explain why that spec workflow matched the change's risk. “Kiro generated a plan” is not the decision.

2. Make Kiro requirements reviewable

A reviewer cannot prove a vague requirement. Replace “the endpoint should be fast” with an observable threshold and measurement boundary. Replace “authorized users can edit” with named roles, allow paths, deny paths, and tenant boundaries. Give each load-bearing criterion a stable identifier so findings and tests can cite it.

Kiro'sAnalyze Requirementspass looks across the requirement set for logical inconsistencies, ambiguities, conflicting constraints, unstated assumptions, and missing edge cases. Run it for complex or domain-sensitive work and after material requirement edits. Resolve or explicitly dismiss each question before treating the spec as the review baseline.

The information-gain principle here is practical: review both directions. Check whether the code satisfies the spec, and whether the spec describes the real contract. An AI reviewer that only asks the first question can confidently approve the wrong behavior.

3. Version Kiro steering and review policy with the change

Kiro's currentsteering documentation describes project files for product, technology, and structure context, plus custom files for focused standards. It also supports root and directory-scopedAGENTS.md files. These are useful inputs to authorship and review, but only when the reviewer can tell which rules applied.

Treat policy changes like code changes. Keep stable product constraints, authorization rules, required test commands, generated-file policy, and compatibility promises in the repository. Put task-specific intent and non-goals in the spec or pull-request description. Theevidence-bound PR review prompts provide reusable correctness, security, testing, migration, and API-compatibility angles.

Custom agents need one extra check. Kiro says steering files are not automatically included for custom agents unless their resource configuration loads them. Do not assume a code-review agent received the same context as the authoring session. Record the agent definition and review-policy revision in the receipt, then inspect the loaded resources before trusting a repository-specific conclusion.

4. Bound Kiro hooks and headless review

Use hooks for short feedback loops. Kiro documentsAgent Stop hooks for compilation, tests, formatting, cleanup, and review after an agent turn. Those checks can catch mistakes before a pull request exists. Keep commands deterministic, repository owned, and narrow enough that a developer can reproduce the result outside Kiro.

For CI, Kiro's headless mode runs a prompt without an interactive terminal. It requires an API key and supports tool-category allowlists. Prefer read and search access for a reviewer; do not grant write or unrestricted shell authority merely because the example finishes faster with every tool trusted.

git diff --no-ext-diff "${BASE_SHA}" "${HEAD_SHA}" |
  kiro-cli chat     --no-interactive     --trust-tools=read,grep     --output-format stream-json     "Review this pull-request diff against the repository's review rules."

This command follows the documented headless shape, but it is not a complete gate. A production workflow must define the diff base, check out the exact pull-request head, handle truncation and operational errors, validate the review output, and publish a commit-bound conclusion. Treat model text and pull-request content as untrusted input. Never execute commands copied from a finding.

5. Capture the exact Kiro-authored pull-request head

Kiro Web can create a feature branch, commit changes, and open a pull request. ItsGitHub integration guide also lets the task owner ask Kiro to address all review comments or one conversation and push updates. Every push changes the review target.

Read the live PR head SHA immediately before review starts. Store it asauthored_head or requested_head. When the review finishes, compare the current PR head again. If the value changed during review, keep the result as historical analysis and request a fresh review. Do not guess that an agent silently incorporated a commit that arrived after its context was assembled.

Kiro's in-session PR view exposes commit SHAs for inspection, while GitHub remains the comment, approval, and merge surface. Use GitHub's API or an equivalent trusted repository query as the source of truth for the current head. The authoring chat is context, not repository state.

6. Convert Kiro code review findings into obligations

A finding becomes a merge obligation only after it passes an evidence threshold. Require the changed file or symbol, the violated requirement or repository rule, a causal path, the concrete consequence, and the correction or evidence needed to close it. Confidence, severity, or forceful wording cannot substitute for those fields.

Thesignal-first review-comment contractseparates defects from questions and optional improvements. It also preserves dispositions such as fixed, rejected with evidence, intentional contract, and needs human judgment. Apply the same model to Kiro output whether it appears in a terminal, a CI log, or a GitHub conversation.

Tie each admitted finding to both the reviewed head and the applicable requirement ID. If the finding reveals a missing requirement, update the spec first, give the new requirement a stable identity, and then fix the code. This prevents the team from closing a real product gap as an undocumented one-off patch.

7. Invalidate old evidence after Kiro changes the branch

Kiro can address pull-request feedback and push another commit. A human or another coding agent can do the same. The author does not matter: a new head changes the code under review and may change the relationship between the implementation and the spec.

1. Capture the old and new head SHAs.
2. Inspect the fix diff against the admitted finding and requirement.
3. Update the spec if the repair changed intended behavior.
4. Run the focused regression on the new head.
5. Run repository-required CI on the new head or applicable test-merge commit.
6. Request a fresh review and reconcile every open obligation.
7. Publish a new verdict only after the reviewed and current heads agree.

GitHub branch protectioncan dismiss stale approvals, require approval of the latest reviewable push, require conversation resolution, and require status checks before merge. Configure the controls that match the repository's risk. A resolved Kiro thread and a green check answer different questions; neither should silently stand in for the other.

8. Require an independent exact-head verdict

Keep the final verdict in repository-owned CI. It should distinguishpassed, needs_changes, and review_error; name the reviewed SHA; preserve structured findings; and fail closed when the reviewer is unavailable or its output is invalid. Branch protection or a ruleset can then require that check from the intended source.

ReviewGate is one open-source implementation of this boundary. It runs in GitHub Actions with a bring-your-own OpenRouter key, publishes a visible 0-5 score in one canonical summary, and emits structured findings for humans or external repair agents. It does not need to replace Kiro's authoring, spec, or feedback surfaces. It evaluates the committed pull-request state and reports the reviewed head.

Install the maintained workflow from theReviewGate GitHub Action guide, then configure scoped review angles and severity through therepository configuration. Use thestructured repair loop to give Kiro or another agent only the open, evidence-backed findings that remain on the current head.

Before requiring any AI review across many repositories, measure it. TheAI code review benchmark scorecardcovers recall, false blockers, repeatability, failure handling, latency, cost, and rollout decisions. A gate earns authority through observed reliability, not through the confidence of its prose.

A worked Kiro spec-to-verdict transition

Consider a Kiro Bugfix Spec for a project-membership endpoint. This is an illustrative workflow, not a claim about a real customer run.

1. The bug analysis states that invited members are incorrectly denied. It also states that unrelated users must remain unable to discover the project. The two behaviors become REQ-3.1 and REQ-3.2.
2. Kiro's design keeps authorization in the existing policy layer. The task list calls for a predicate fix plus allow and deny regressions. The spec files and steering rules are committed as revision S.
3. Kiro implements the tasks and opens a PR at head A. A headless review finds that the new predicate admits suspended members. The maintainer accepts the finding because it cites the changed branch, the account-status rule, and a reachable consequence.
4. The spec gains REQ-3.3 for suspended members. Kiro updates the predicate and adds a regression, creating head B. Review evidence for head A moves to history.
5. Focused authorization tests, required CI, and ReviewGate run on headB. The structured result names B, scores the review 5/5, and has no unresolved blocker. The current PR head is still B when a maintainer merges.

The useful result is not “Kiro fixed its own code.” The repository can show how a discovered gap changed the specification, which commit implemented it, which tests exercised it, and which independent verdict covered the code that merged.

Should you use Kiro, ReviewGate, or both?

Kiro is the stronger fit when the job begins with uncertain requirements or needs an agent to plan, implement, and revise a change. ReviewGate is intentionally narrower: it supplies a repository-owned review artifact and visible merge signal. The combination is useful when the same agent can author and repair the code but the repository needs a separate exact-head decision boundary.

Common Kiro code review failure modes

Reviewing the diff but not the specification

Correct code can implement the wrong requirement. Challenge ambiguous, conflicting, and missing behaviors before treating the spec as authority. Link every important finding and regression to a stable requirement ID.

Assuming a custom reviewer loaded all steering

Kiro custom agents require steering resources to be included explicitly. Inspect the agent definition and record the applicable policy revision. A repository-aware conclusion is not credible when the reviewer never received the repository rules.

Granting broad tool access to a read-only reviewer

Use the smallest tool categories that can inspect the change. A reviewer rarely needs mutation authority. Keep shell commands allowlisted, treat model output as untrusted, and prevent pull-request text from becoming executable instructions.

Treating task completion as test evidence

A checked task records progress. It does not prove an acceptance criterion holds. Run repository-owned focused tests and required CI on the exact current head, then record those results separately from the Kiro task list.

Keeping a green result after Kiro pushes a fix

A new commit creates a new review target. Preserve earlier findings as history, inspect the repair, rerun tests, and publish a fresh verdict. Do not equate a resolved conversation with validated code.

Turning reviewer failure into a clean review

Authentication errors, model timeouts, malformed output, missing context, and truncated diffs are operational failures. Report them as inconclusive and retry; never translate unavailable evidence into a passed gate.

Questions about Kiro code review

Add an exact-head gate after Kiro

ReviewGate is free and open source. It runs inside GitHub Actions, uses your OpenRouter key, updates one score-centered summary, and emits structured findings for the reviewed head. Keep Kiro for specs, implementation, and repairs; use the independent gate to decide whether the current commit is ready for a human merge decision.