Agent-Native Reviewer
Review whether an agent can perform, verify, and discover the same meaningful
action a user can.
The standard is simple:
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
- Action parity. Every important user action has an agent route.
- Context parity. Agents can see the inputs, state, and constraints needed
to act well.
- Source ownership. Agents edit the durable source, not generated mirrors
or copied output.
- Proof parity. Agents can verify the outcome with the same authority a
maintainer would trust.
- Discoverability. The route is visible from the skill, AGENTS file,
command docs, tool schema, or public API docs an agent is expected to read.
- 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:
- 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.
- 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.
- 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.
- 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
## 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
- ...
1---2name: agent-native-reviewer-23description: Review agent-native parity for skills, prompts, tools, commands, generated mirrors, repo workflows, and user-facing actions.4---56# Agent-Native Reviewer78Review whether an agent can perform, verify, and discover the same meaningful9action a user can.1011The standard is simple:1213```txt14user action -> agent route -> source owner -> proof command/artifact -> handoff15```1617If one link is missing, the workflow is not agent-native.1819## Use When2021- `.agents/**`, `.claude/**`, `.codex/**`, skills, prompts, hooks, commands, or22 workflow docs changed.23- A feature adds or changes a user-facing action and the repo has agent24 integration.25- A reviewer asks whether Codex can reproduce, operate, verify, or maintain the26 same surface a human can.27- A repo is becoming mostly agent-maintained and needs fewer hidden human-only28 paths.2930## Do Not Use When3132- The task is a normal code review with no agent/tooling/workflow surface.33- The action is intentionally human-only: MFA, OAuth consent, billing payment34 entry, CAPTCHA, legal acceptance, biometric unlock, or OS permission prompts.35- The change is cosmetic and has no meaningful operation to reproduce.3637## Core Principles38391. **Action parity.** Every important user action has an agent route.402. **Context parity.** Agents can see the inputs, state, and constraints needed41 to act well.423. **Source ownership.** Agents edit the durable source, not generated mirrors43 or copied output.444. **Proof parity.** Agents can verify the outcome with the same authority a45 maintainer would trust.465. **Discoverability.** The route is visible from the skill, AGENTS file,47 command docs, tool schema, or public API docs an agent is expected to read.486. **Shared workspace.** Agent-created artifacts live where humans can inspect,49 edit, and commit them.5051## Codex Capability Ladder5253Assume Codex is the agent runtime unless the repo says otherwise. Prefer the54most repeatable proof and interaction layer that can cover the action:55561. **Tests and scripts first.** Unit, integration, browser-test, benchmark,57 typecheck, lint, import smoke, generated-mirror audit, and source audit are58 the default proof layer. If a behavior can be proved there, do that before59 driving an app by hand.602. **Browser next.** Use the Browser plugin for app/browser interaction proof61 when tests cannot fully prove rendered behavior, native selection, focus,62 navigation, screenshots, console/network state, or real route behavior.633. **Chrome after Browser.** Use Chrome when the task depends on the user's64 existing Chrome state, profile, tabs, extensions, cookies, or a site state65 that Browser cannot access.664. **Computer Use last.** Use Computer Use for OS-level or native-app actions67 that tests, Browser, and Chrome cannot reach. Treat it as powerful but68 brittle; record exact manual proof and any limits.6970Do not jump straight to UI automation when a focused test, command, or source71audit gives stronger evidence. Do not claim a behavior is agent-native unless72the selected layer can be rerun or described precisely enough for another agent73to repeat.7475## Dotai Integrations7677- Use `autogoal` for durable or measurable work. The first checkpoint must copy78 agent-native requirements into the plan before implementation.79- Use `sync-skills` when a skill, rule, template, or generated mirror crosses80 repo boundaries. Shared behavior belongs in dotai; repo policy stays local.81- Use `sync-vision` when the missing parity is reusable taste or doctrine, not82 just one task's mechanics.83- Use `resolve-pr-feedback` for PR review feedback. Do not nest mandatory84 `autoreview`; only recommend it after a complete end-to-end feature when an85 optional independent second pass could materially help.86- Use `hard-cut` when stale compatibility, fake aliases, dead commands, or87 duplicate agent routes should be deleted rather than wrapped.88- Use `tdd` or `diagnosing-bugs` when the parity gap is a real behavior bug,89 flaky proof, or unclear failure path.9091## Review Process9293### 1. Identify the Changed Surface9495Classify the action surface:9697| Surface | Examples |98|---|---|99| Skill/workflow | `SKILL.md`, `.mdc`, plan template, generated mirror, lockfile |100| Command/tool | CLI command, script, MCP tool, GitHub workflow, package script |101| Public API | exported package API, docs example, release artifact |102| Product action | button, form, keyboard shortcut, browser route, OS/device path |103| Maintainer action | issue triage, PR feedback, security advisory, release lane |104105For incremental reviews, start from the changed files and expand only to the106source owner, generated mirror, lockfile, command, or docs that prove parity.107108### 2. Build the Parity Map109110Use this map for every meaningful action:111112| User action | Agent route | Source owner | Mirror/lock/doc | Proof | Status |113|---|---|---|---|---|---|114| action | skill/tool/command | file/path | generated/config/doc | command/artifact | pass/gap/N/A |115116Status rules:117118- `pass`: source owner, route, proof, and discoverability are present.119- `gap`: agent cannot safely perform or verify the action.120- `N/A`: intentionally human-only or outside the current repo authority, with a121 concrete reason.122123### 3. Check Source Ownership124125Flag any workflow that asks agents to edit output instead of source.126127Common source boundaries:128129| Output | Source owner |130|---|---|131| `.agents/skills/**/SKILL.md` installed mirror | external skill package or `.agents/rules/**` source |132| `.claude/skills/**/SKILL.md` installed mirror | external skill package or `.agents/rules/**` source |133| root `AGENTS.md` generated block | `.agents/AGENTS.md` or repo generator input |134| generated barrel/export file | package source plus barrel generator command |135| generated docs/template output | registry/package/docs source named by repo policy |136| copied skill in many repos | dotai source plus Skills CLI install/update |137138Finding severity is high when the wrong owner would make future agents lose the139fix during sync.140141### 4. Check Agent Route142143The route must be usable without hidden human context:144145- skill name or tool is discoverable from the available skill list, `AGENTS.md`,146 README, or command docs;147- arguments are explicit enough for an agent to call correctly;148- required credentials, browser state, local env, or external access are named;149- authority boundaries are clear: read-only, patch, commit, push, comment,150 merge, publish, delete.151152Do not demand a wrapper skill for every small action. Prefer patching the owner153skill, AGENTS routing, or command docs when an existing route fits.154155### 5. Check Proof156157Every important agent action needs a verification path:158159- exact command, cwd, and expected result;160- generated mirror or lockfile audit;161- browser route/screenshot/console caveat when UI behavior changed;162- issue/PR/security fetch when public maintainer state changed;163- source audit when the claim is structural;164- `N/A` reason when no automated proof fits.165166Proof must run in the owning workspace. A downstream install is not proved by a167source-package validation alone, and a source-package change is not proved by a168downstream command alone.169170### 6. Check Context171172Agents need the same operational context a human maintainer uses:173174- the relevant vision/doctrine file is linked or routed;175- project-specific commands live in the project, not in dotai;176- final handoff tells the user what changed, what needs attention, and what was177 not verified;178- recurring misses are written into the durable owner, not left in chat.179180If the missing context is reusable taste, route to `sync-vision`. If it is181workflow mechanics, patch the skill/template. If it is one-off, record it in the182active plan or final handoff.183184## Findings185186Use severity by consequence:187188- `P0`: agent can perform a destructive/public action without authority or189 proof.190- `P1`: important user or maintainer action has no safe agent route, or the191 source/generated boundary is wrong.192- `P2`: route exists but is hard to discover, lacks proof, or will rot during193 sync.194- `P3`: wording or docs polish that would improve agent success but is not a195 blocker.196197Suppress low-confidence guesses. If runtime observation is required, ask for or198run the proof instead of inventing a finding.199200## What Not To Flag201202- Human-only security/legal/payment ceremonies.203- Cosmetic UI actions without operational meaning.204- Missing automation for rare admin tasks when the repo has no safe authority205 model for agents.206- A repo-local fork that intentionally keeps product policy out of dotai.207- A generated mirror that is stale only because the required sync command has208 not run yet; request the sync/proof instead.209210## Output Format211212```md213## Agent-Native Review214215### Verdict216PASS | NEEDS WORK217218### Capability Map219| User action | Agent route | Source owner | Mirror/lock/doc | Proof | Status |220|---|---|---|---|---|---|221222### Findings2231. [P1] Title -- `file:line`224 Impact: ...225 Fix: ...226 Proof: ...227228### Accepted / Rejected229- Accepted: ...230- Rejected: ... because ...231232### Verification233- command or source audit -> result234235### Needs Attention236- ...237```