Reviews

Review loop:

1. Request review (oat-project-review-provide)
2. Receive review and convert findings into tasks (oat-project-review-receive)
3. Implement fixes (oat-project-implement)
4. Re-review until passing status

Storage contract

• New project review artifacts are written to tracked reviews/ directories.
• oat-project-review-receive consumes the active top-level review artifact, updates project bookkeeping, then archives that artifact to reviews/archived/.
• reviews/archived/ is the local-only historical surface. Active reviews/ content is not gitignored by default.
• Ad-hoc review artifacts still default to local-only orphan storage under .oat/projects/local/orphan-reviews/.

Bookkeeping commits (required)

Both oat-project-review-receive and oat-project-review-receive-remote conclude with a required atomic commit of plan.md, implementation.md, state.md, and the archived review artifact (when tracked). This is the safety net that prevents cross-agent bookkeeping drift: when a subagent runs a receive skill in isolation, the commit ensures the original agent sees a clean checkout on return.

The commit is scoped and explicit — it stages only the project's tracking files and the project's reviews/ directory. It never uses git add -A or repo-wide glob patterns. Deferring this commit requires explicit user approval and must be recorded in the receive skill's summary so the original agent knows state is uncommitted.

Project vs ad-hoc

Provide (request a review):

• oat-project-review-provide is project-scoped and requires active project state (resolved via oat config get activeProject / .oat/config.local.json) plus project state.md.
• oat-review-provide is for non-project commit-range reviews (ad-hoc, no project state required).

Receive (process review findings):

• oat-project-review-receive processes local review artifacts within a project context (converts findings to plan tasks).
• oat-project-review-receive-remote processes GitHub PR comment feedback within a project context (converts findings to plan tasks with stable pNN-tNN IDs).
• oat-review-receive processes local review artifacts in ad-hoc mode (standalone task-list output, no project state mutation).
• oat-review-receive-remote processes GitHub PR comment feedback in ad-hoc mode (standalone task-list output, optional reply posting).

Status model

Status progression in plan.md Reviews table:

• pending
• received
• fixes_added
• fixes_completed
• passed

Current policy

• Critical/Important: address before pass.
• Medium: address by default; defer only with explicit approval and recorded rationale/disposition.
• Minor (non-final scopes): auto-deferred by default with rationale; do not block review completion.
• Minor (final scope): not auto-deferred; require explicit user disposition (defer vs convert), and explain each minor in plain language before asking.

Auto-review at checkpoints

When autoReviewAtCheckpoints is enabled (via oat config set autoReviewAtCheckpoints true or per-project in plan.md frontmatter), completing a plan phase checkpoint automatically spawns a subagent review. The review scope covers every implementation phase not already covered by a passed whole-phase code review, through the just-completed checkpoint. Mid-implementation multi-phase checkpoint reviews use inclusive phase-range scopes such as p02-p03. The final phase checkpoint triggers a code final review.

Auto-triggered reviews use oat_review_invocation: auto in the review artifact frontmatter. In auto mode, oat-project-review-receive auto-converts all findings to fix tasks without user prompts (Minor findings that are clearly out of scope are deferred with a note).

This feature is opt-in and disabled by default. When disabled, the manual oat-project-review-provide workflow applies.

Re-review scope narrowing

When re-reviewing after fix tasks have been applied, oat-project-review-provide detects completed (review) fix tasks and offers to narrow the re-review scope to just the fix-task commits. This avoids re-examining already-approved code.

The behavior can be set as a default via workflow.autoNarrowReReviewScope:

• true — automatically narrow to fix commits, no prompt
• false — always use the full scope, no prompt
• unset (default) — prompt the user on each re-review

Typically set at user scope since it's a personal workflow preference:

oat config set workflow.autoNarrowReReviewScope true --user

The preference only applies when there are completed fix tasks to narrow to. Initial reviews (before any fix tasks exist) always use the full scope regardless of the preference. See Workflow preferences in the Configuration guide for the full list of preference keys.

Phase and final review

Use phase-scoped review artifacts during implementation (p01, p02, etc), then run final review before project closeout.

Final review passed gate requires:

• No unresolved Critical/Important/Medium findings.
• Deferred Medium findings resurfaced and explicitly dispositioned.
• Minor findings explicitly dispositioned (after plain-language explanation).

Subagent Compatibility

oat-project-review-provide uses provider-aware subagent dispatch when available:

• Claude Code: dispatch oat-reviewer with subagent_type (resolved from .claude/agents/oat-reviewer.md).
• Cursor: dispatch oat-reviewer via explicit /oat-reviewer invocation or natural mention (resolved from .cursor/agents/oat-reviewer.md; .claude/agents/oat-reviewer.md is also supported for compatibility).
• Codex multi-agent runtimes: Codex can auto-decide when to spawn agents, or you can explicitly request agent spawning (optionally with agent_type).
  • Requires Codex config prerequisites:
    • [features] multi_agent = true
    • If explicit role pinning is used, role must be built-in (default/worker/explorer) or configured under [agents.<name>].
  • Project-scope Codex role files are generated from canonical .agents/agents/*.md during oat sync --scope project.
  • User-scope Codex role generation (~/.codex) is intentionally deferred.
  • Some Codex hosts require explicit user authorization before the skill may call spawn_agent. In those hosts, oat-project-review-provide should ask whether to delegate to oat-reviewer instead of reporting the reviewer as unresolved.
• If subagent dispatch is unavailable, follow the existing fallback path (fresh session preferred, inline reset as fallback).

Reference artifacts

• .oat/projects/<scope>/<project>/plan.md (## Reviews)
• .oat/projects/<scope>/<project>/reviews/ (active tracked review artifacts)
• .oat/projects/<scope>/<project>/reviews/archived/ (local-only historical review artifacts)
• .oat/projects/local/orphan-reviews/ (default local-only storage for ad-hoc review artifacts)
• .oat/repo/reviews/ (tracked storage convention when explicitly desired)
• .agents/skills/oat-review-provide/SKILL.md
• .agents/skills/oat-review-receive/SKILL.md
• .agents/skills/oat-review-receive-remote/SKILL.md
• .agents/skills/oat-project-review-provide/SKILL.md
• .agents/skills/oat-project-review-receive/SKILL.md
• .agents/skills/oat-project-review-receive-remote/SKILL.md