agent-native-reviewer

# Agent-Native Reviewer Review whether an agent can perform, verify, and discover the same meaningful action a user can. The standard is simple: ```txt user action -> agent route -> source owner -> proof command/artifact -> handoff ``` If one link is missing, the workflow is not agent-native. ## Use When - `.agents/**`, `.claude/**`, `.codex/**`, skills, prompts, hooks, commands, or workflow docs changed. - A feature adds or changes a user-facing action and the repo has agent integration. - A reviewer asks whether Codex can reproduce, operate, verify, or maintain the same surface a human can. - A repo is becoming mostly agent-maintained and needs fewer hidden human-only paths. ## Do Not Use When - The task is a normal code review with no agent/tooling/workflow surface. - The action is intentionally human-only: MFA, OAuth consent, billing payment entry, CAPTCHA, legal acceptance, biometric unlock, or OS permission prompts. - The change is cosmetic and has no meaningful operation to reproduce. ## Core Principles 1. **Action parity.** Every important user action has an agent route. 2. **Context parity.** Agents can see the inputs, state, and constraints needed to act well. 3. **Source ownership.** Agents edit the durable source, not generated mirrors or copied output. 4. **Proof parity.** Agents can verify the outcome with the same authority a maintainer would trust. 5. **Discoverability.** The route is visible from the skill, AGENTS file, command docs, tool schema, or public API docs an agent is expected to read. 6. **Shared workspace.** Agent-created artifacts live where humans can inspect, edit, and commit them. ## Codex Capability Ladder Assume Codex is the agent runtime unless the repo says otherwise. Prefer the most repeatable proof and interaction layer that can cover the action: 1. **Tests and scripts first.** Unit, integration, browser-test, benchmark, typecheck, lint, import smoke, generated-mirror audit, and source audit are the default proof layer. If a behavior can be proved there, do that before driving an app by hand. 2. **Browser next.** Use the Browser plugin for app/browser interaction proof when tests cannot fully prove rendered behavior, native selection, focus, navigation, screenshots, console/network state, or real route behavior. 3. **Chrome after Browser.** Use Chrome when the task depends on the user's existing Chrome state, profile, tabs, extensions, cookies, or a site state that Browser cannot access. 4. **Computer Use last.** Use Computer Use for OS-level or native-app actions that tests, Browser, and Chrome cannot reach. Treat it as powerful but brittle; record exact manual proof and any limits. Do not jump straight to UI automation when a focused test, command, or source audit gives stronger evidence. Do not claim a behavior is agent-native unless the selected layer can be rerun or described precisely enough for another agent to repeat. ## Dotai Integrations - Use `autogoal` for durable or measurable work. The first checkpoint must copy agent-native requirements into the plan before implementation. - Use `sync-skills` when a skill, rule, template, or generated mirror crosses repo boundaries. Shared behavior belongs in dotai; repo policy stays local. - Use `sync-vision` when the missing parity is reusable taste or doctrine, not just one task's mechanics. - Use `resolve-pr-feedback` for PR review feedback. Do not nest mandatory `autoreview`; only recommend it after a complete end-to-end feature when an optional independent second pass could materially help. - Use `hard-cut` when stale compatibility, fake aliases, dead commands, or duplicate agent routes should be deleted rather than wrapped. - Use `tdd` or `diagnosing-bugs` when the parity gap is a real behavior bug, flaky proof, or unclear failure path. ## Review Process ### 1. Identify the Changed Surface Classify the action surface: | Surface | Examples | |---|---| | Skill/workflow | `SKILL.md`, `.mdc`, plan template, generated mirror, lockfile | | Command/tool | CLI command, script, MCP tool, GitHub workflow, package script | | Public API | exported package API, docs example, release artifact | | Product action | button, form, keyboard shortcut, browser route, OS/device path | | Maintainer action | issue triage, PR feedback, security advisory, release lane | For incremental reviews, start from the changed files and expand only to the source owner, generated mirror, lockfile, command, or docs that prove parity. ### 2. Build the Parity Map Use this map for every meaningful action: | User action | Agent route | Source owner | Mirror/lock/doc | Proof | Status | |---|---|---|---|---|---| | action | skill/tool/command | file/path | generated/config/doc | command/artifact | pass/gap/N/A | Status rules: - `pass`: source owner, route, proof, and discoverability are present. - `gap`: agent cannot safely perform or verify the action. - `N/A`: intentionally human-only or outside the current repo authority, with a concrete reason. ### 3. Check Source Ownership Flag any workflow that asks agents to edit output instead of source. Common source boundaries: | Output | Source owner | |---|---| | `.agents/skills/**/SKILL.md` installed mirror | external skill package or `.agents/rules/**` source | | `.claude/skills/**/SKILL.md` installed mirror | external skill package or `.agents/rules/**` source | | root `AGENTS.md` generated block | `.agents/AGENTS.md` or repo generator input | | generated barrel/export file | package source plus barrel generator command | | generated docs/template output | registry/package/docs source named by repo policy | | copied skill in many repos | dotai source plus Skills CLI install/update | Finding severity is high when the wrong owner would make future agents lose the fix during sync. ### 4. Check Agent Route The route must be usable without hidden human context: - skill name or tool is discoverable from the available skill list, `AGENTS.md`, README, or command docs; - arguments are explicit enough for an agent to call correctly; - required credentials, browser state, local env, or external access are named; - authority boundaries are clear: read-only, patch, commit, push, comment, merge, publish, delete. Do not demand a wrapper skill for every small action. Prefer patching the owner skill, AGENTS routing, or command docs when an existing route fits. ### 5. Check Proof Every important agent action needs a verification path: - exact command, cwd, and expected result; - generated mirror or lockfile audit; - browser route/screenshot/console caveat when UI behavior changed; - issue/PR/security fetch when public maintainer state changed; - source audit when the claim is structural; - `N/A` reason when no automated proof fits. Proof must run in the owning workspace. A downstream install is not proved by a source-package validation alone, and a source-package change is not proved by a downstream command alone. ### 6. Check Context Agents need the same operational context a human maintainer uses: - the relevant vision/doctrine file is linked or routed; - project-specific commands live in the project, not in dotai; - final handoff tells the user what changed, what needs attention, and what was not verified; - recurring misses are written into the durable owner, not left in chat. If the missing context is reusable taste, route to `sync-vision`. If it is workflow mechanics, patch the skill/template. If it is one-off, record it in the active plan or final handoff. ## Findings Use severity by consequence: - `P0`: agent can perform a destructive/public action without authority or proof. - `P1`: important user or maintainer action has no safe agent route, or the source/generated boundary is wrong. - `P2`: route exists but is hard to discover, lacks proof, or will rot during sync. - `P3`: wording or docs polish that would improve agent success but is not a blocker. Suppress low-confidence guesses. If runtime observation is required, ask for or run the proof instead of inventing a finding. ## What Not To Flag - Human-only security/legal/payment ceremonies. - Cosmetic UI actions without operational meaning. - Missing automation for rare admin tasks when the repo has no safe authority model for agents. - A repo-local fork that intentionally keeps product policy out of dotai. - A generated mirror that is stale only because the required sync command has not run yet; request the sync/proof instead. ## Output Format ```md ## Agent-Native Review ### Verdict PASS | NEEDS WORK ### Capability Map | User action | Agent route | Source owner | Mirror/lock/doc | Proof | Status | |---|---|---|---|---|---| ### Findings 1. [P1] Title -- `file:line` Impact: ... Fix: ... Proof: ... ### Accepted / Rejected - Accepted: ... - Rejected: ... because ... ### Verification - command or source audit -> result ### Needs Attention - ... ```