agent-native-audit

What It Does

Step-by-step audit procedure for evaluating a codebase's agent-native
architecture maturity. Where agent-native-architecture codifies the
principles, this skill codifies the audit process — what to inventory,
what to measure, what to flag. The
yellow-review:review:agent-native-reviewer agent uses this checklist for
incremental PR reviews; full audits (such as yellow-debt's audit workflow)
use it for codebase-wide assessments.

When to Use

• Onboarding to a codebase that has agent integration and you need to
  understand its current parity status.
• Before adding a new agent capability — confirm existing patterns first.
• Auditing a codebase that's adding agent integration for the first time —
  identify the orphan-feature surface area.
• Triaging "the agent feels broken" complaints — narrow to which principle
  is failing.

Usage

Step 0: Triage

Answer three questions before scanning:

1. Does this codebase have agent integration at all? Search for tool
   definitions, system prompt construction, or LLM API calls. If none
   exists, every user-facing action is an orphan feature — that is the
   single top finding. Recommend where agent integration should be
   introduced.

2. What stack? Identify where UI actions and agent tools are defined
   using the table in agent-native-architecture skill.

3. Incremental or full audit? For a PR review, focus on new/modified
   code. For a full audit, scan systematically.

Step 1: Map the Landscape

Inventory:

• UI actions — buttons, forms, navigation links, gestures, keyboard
  shortcuts. Grep for onClick, onSubmit, onTap, Button,
  onPressed, form actions.
• Agent tools — tool definitions and where registered. Grep for
  tool(, function_call, tools:, framework-specific decorators.
• System prompt construction — static string vs. dynamically built
  with runtime state. Grep for prompt template strings, prompt-builder
  functions.
• Context sources — where the agent gets information about resources,
  recent activity, capabilities, vocabulary.

Step 2: Build the Capability Map

Cross-reference UI actions against agent tools:

| UI Action | Location | Agent Tool | In Prompt? | Priority | Status |
|-----------|----------|------------|------------|----------|--------|
| Rename project | src/projects/RenameDialog.tsx | rename_project | yes | must-have | OK |
| Archive project | src/projects/ArchiveBtn.tsx | (none) | n/a | must-have | GAP |
| Theme toggle | src/settings/Theme.tsx | (none) | n/a | low | observation |

Flag must-have and should-have gaps as Critical or Warning. Low-priority
gaps are Observations only.

Step 3: Check Context Parity

Verify the system prompt includes:

• Available resources — files, data, entities the user can see
• Recent activity — what the user has done recently
• Capabilities mapping — what tool does what
• Domain vocabulary — app-specific terms explained

Red flags:

• System prompt is a static constant string with no runtime substitution
• Agent doesn't know what resources exist (asks "what's the project name?"
  when the project context should be injected)
• Agent doesn't understand app-specific terms

Step 4: Check Tool Design

For each tool:

• Inputs are data, not decisions — store(key, value) is data;
  process(message) with internal categorization is a decision tool.
• Output is rich enough to verify success — return IDs, URLs, or
  structured confirmation, not just "Done!".
• Errors are actionable — tell the agent what to try next.
• Idempotent if commonly retried — or returns audit-friendly
  output (timestamps, request IDs).

Workflow-tool detection:

• Tool body branches on input data (if (priority > 3), switch (category))
• Tool calls multiple downstream services in sequence
• Tool returns success regardless of which path it took (no surface for
  the agent to reason about which thing happened)

Step 5: Check Shared Workspace

• Agent file operations use the same paths as the UI?
• UI observes changes the agent makes (file watching, reactive store)?
• No separate "agent sandbox"?
• Users can inspect and edit agent-created artifacts?

Step 6: The Noun Test

After actions, audit by domain object. For every noun in the app,
the agent should:

1. Know what it is (context injection)
2. Have a tool to interact with it
3. See it documented in the system prompt

A noun failing all three is critical for must-have entities.

Output

A capability map with status column, a list of gaps grouped by priority
tier, and a verdict: PASS / NEEDS WORK / CRITICAL.

## Agent-Native Architecture Audit

### Summary
[App type, agent integration present, parity assessment]

### Capability Map
[Table from Step 2]

### Findings

#### Critical (Must Fix)
1. **[Issue]** — `file:line` — [Description]. Fix: [How]

#### Warnings (Should Fix)
1. **[Issue]** — `file:line` — [Description]. Recommendation: [How]

#### Observations
1. **[Observation]** — [Description]

### What's Working Well
- [Positive observations]

### Score
- **X/Y high-priority capabilities are agent-accessible**
- **Verdict:** PASS / NEEDS WORK / CRITICAL

What This Skill Doesn't Cover

• The principles themselves — see agent-native-architecture skill
  for the canonical reference.
• CLI agent-readiness — see cli-readiness-reviewer and
  agent-cli-readiness-reviewer agents (yellow-review).
• Generic code review — this is a domain-specific audit; pair with
  correctness-reviewer, security-sentinel, etc. for full coverage.