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.

1. Source ownership. Agents edit the durable source, not generated mirrors

or copied output.

1. Proof parity. Agents can verify the outcome with the same authority a

maintainer would trust.

1. Discoverability. The route is visible from the skill, AGENTS file,

command docs, tool schema, or public API docs an agent is expected to read.

1. 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.

1. 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.

1. 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.

1. 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
- ...