agent-native-reviewer

name	agent-native-reviewer
description	Review agent-native parity for skills, prompts, tools, commands, generated mirrors, repo workflows, and user-facing actions.

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

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

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