Agent-Native Architecture

patterns ~4707 tokens updated 2026-06-22

Principles and audit skill for building applications where an agent is a first-class user. Four principles (parity, granularity, composability, emergent capability) as a rule file, a self-eval / red-team rubric that scores a surface against those principles, plus /agent-native-audit that scores a codebase with specific counts and a reviewer persona for the unified review orchestrator.

README

Agent-Native Architecture

Principles and tooling for designing applications where an LLM agent is a first-class user. Ship it when you are building or auditing a product that an agent will drive on behalf of a human.

The module installs four things: a rule file with the four principles, a self-eval / red-team rubric that scores a surface against those principles, a /agent-native-audit skill that scores a codebase against them, and a reviewer persona for the unified review orchestrator (CCGM #277).

The Four Principles

Parity - Whatever the user can do in the UI, the agent can do via a tool.
Granularity - Prefer atomic primitives. Features are outcomes achieved by an agent composing primitives in a loop.
Composability - New features become new prompts, not new code.
Emergent Capability - The agent accomplishes things the product team did not explicitly design for.

Full discussion with design-time guidance, runtime guidance, anti-patterns, and scope guidance in rules/agent-native.md.

What This Module Provides

Files installed globally to ~/.claude/:

Source	Target	Purpose
`rules/agent-native.md`	`rules/agent-native.md`	Four principles with one section each plus design, runtime, and audit guidance
`rules/agent-native-self-eval.md`	`rules/agent-native-self-eval.md`	Self-eval / red-team rubric: reference surface spec, parallel red-team procedure, pass criteria, and scoring
`skills/agent-native-audit/SKILL.md`	`skills/agent-native-audit/SKILL.md`	`/agent-native-audit` - score a codebase with specific counts and concrete fixes
`agents/reviewers/agent-native-reviewer.md`	`agents/reviewers/agent-native-reviewer.md`	Reviewer persona for `/ce-review` and standalone diff review

Manual Installation

# From the CCGM repo root:

mkdir -p ~/.claude/rules
mkdir -p ~/.claude/skills/agent-native-audit
mkdir -p ~/.claude/agents/reviewers

cp modules/agent-native/rules/agent-native.md \
   ~/.claude/rules/agent-native.md

cp modules/agent-native/rules/agent-native-self-eval.md \
   ~/.claude/rules/agent-native-self-eval.md

cp modules/agent-native/skills/agent-native-audit/SKILL.md \
   ~/.claude/skills/agent-native-audit/SKILL.md

cp modules/agent-native/agents/reviewers/agent-native-reviewer.md \
   ~/.claude/agents/reviewers/agent-native-reviewer.md

Usage

Audit a codebase

/agent-native-audit
/agent-native-audit apps/web
/agent-native-audit focus:parity
/agent-native-audit mode:report-only
/agent-native-audit mode:headless

The skill dispatches eight parallel subagents - two per principle, one measuring and one critiquing. It returns a scorecard out of 100 with bands (absent / emerging / solid / exemplary), a Top-5 Findings section with file:line evidence, and probe prompts that surface whether emergent capability exists.

Full mode writes the report to .agent-native-audit/{timestamp}.md so you can diff future runs. Report-only mode writes nothing. Headless mode returns a structured JSON envelope for skill-to-skill invocation.

Review a diff

Dispatch the agent-native-reviewer agent directly, or invoke it as one lens inside the unified review orchestrator (CCGM #277):

Dispatch agent-native-reviewer with:
- diff: <unified diff or file list>
- repo_path: <absolute path>
- focus: parity | granularity | composability | emergent | all

The reviewer returns a structured critique with a verdict (approve / approve-with-concerns / request-changes), principle-level deltas versus a prior audit if provided, and a Findings list with file:line evidence and suggested changes.

Self-eval / red-team a surface

Use rules/agent-native-self-eval.md to score whether a surface is genuinely agent-native and resilient. It defines a reference test surface (a small social-feed system with 12 minimum tools), a parallel red-team procedure that dispatches N agents against the deployed surface per the subagent-patterns dispatch model, and a pass/fail scorecard (zero exploits, >= 85% parity, >= 3/5 emergent prompts, zero granularity violations, error-quality spot-check). A red-team-free manual checklist is included for solo evaluation. The rubric doubles as a consistent standard for assessing agentic engineering work.

Use the rule as design guidance

Reference rules/agent-native.md when writing a system prompt for an AI assistant layer, when RFC-ing a new product surface, or when sketching the tool signature for a new feature. The design-time, runtime, and anti-patterns sections are structured for that use.

Dependencies

subagent-patterns - the audit skill uses the pass-paths-not-contents pattern and the mode token convention from modules/subagent-patterns/rules/subagent-patterns.md.

No runtime dependencies beyond the module system.

Non-Goals

This module does not:

Ship a reference agent-native application. The rules and audit target existing codebases.
Auto-fix violations. The audit produces findings and proposed PRs; humans decide which to land.
Replace general code review. Parity, granularity, composability, and emergent capability are one lens among many (security, tests, prose, accessibility). The reviewer persona is scoped to this lens only.
Wire itself into /ce-review. The reviewer persona is available; the orchestrator invocation is tracked in CCGM #277.

Source

Adapted from EveryInc/compound-engineering-plugin. The original ships skills/agent-native-architecture/SKILL.md (principle doc as a skill), skills/agent-native-audit/SKILL.md, and agents/review/agent-native-reviewer.md as part of a larger review orchestrator.

Adaptations from the source:

The principle document is a rule file (installs to ~/.claude/rules/) rather than a skill, so other rules and commands can reference it without invoking a skill.
The audit skill uses the CCGM mode token convention (mode:full, mode:report-only, mode:headless) and the pass-paths-not-contents subagent dispatch pattern.
The reviewer persona lives under agents/reviewers/ per the agents/ convention added in CCGM #273, so the unified review orchestrator (CCGM #277) can discover it.
The fan-out is eight agents (two per principle - one measures, one critiques) rather than four, matching the density of evidence each principle needs.

Will install

Path	Action	Target	Type
`rules/agent-native.md`	→	`rules/agent-native.md`	rule
`rules/agent-native-self-eval.md`	→	`rules/agent-native-self-eval.md`	rule
`skills/agent-native-audit/SKILL.md`	→	`skills/agent-native-audit/SKILL.md`	skill
`agents/reviewers/agent-native-reviewer.md`	→	`agents/reviewers/agent-native-reviewer.md`	agent

Dependencies

subagent-patterns

Required by

No other module depends on this one.

Included in presets

Install this module

Agent prompt

Recommended for agent users -- hands the whole install off to your assistant.

Fetch https://cd23a9be.ccgm-site.pages.dev/modules/agent-native.md and install this module into my Claude Code setup.

Native plugin marketplace

One command via the native plugin marketplace -- additive, does not merge settings.json.

claude plugin install agent-native@ccgm

The marketplace path is additive, not a replacement: it installs commands, agents, and skills as native plugin components, but it does not perform the bash installer's deep settings.json merge, and it does not write the always-loaded global CLAUDE.md context. Rules are only injected via an opt-in SessionStart hook rather than being auto-loaded. Use the bash installer when those pieces matter to you.

Manual, per file

Full control -- copy exactly the files you want from the sections below.

Files

rule (2)

rules/agent-native.md

# Agent-Native Architecture

Principles for building applications where an LLM agent is a first-class user, not an afterthought. Use these when designing product surfaces (APIs, tools, data models, workflows) that an agent must drive on behalf of a human.

An application is "agent-native" when an agent can accomplish anything a user can, using structured tools the application exposes, and when the agent can compose those tools to produce behavior the original designers did not explicitly build.

## The Four Principles

### 1. Parity

**Whatever the user can do in the UI, the agent can do via a tool.**

Every user-visible action maps to a callable tool with the same semantics, same permissions, and same resulting state. No "UI-only" flows, no "this one is a button that pops a modal you can only dismiss with a click." If the flow exists in the product, the agent has a tool for it.

Parity is measurable. Count the distinct user actions exposed in the UI. Count the tools an agent can invoke. The ratio tells you whether the agent is a first-class user or a second-class one. A parity of `agent can do X of Y user actions` is a concrete audit output.

Violations to watch for:
- Buttons whose handlers cannot be reached from any tool
- Drag-and-drop or gesture interactions with no programmatic equivalent
- Hidden side effects that fire only on UI events (analytics, optimistic updates, toasts) and that the agent has no way to trigger or observe

### 2. Granularity

**Prefer atomic primitives. Features are outcomes the agent achieves by composing primitives in a loop.**

A product that ships one tool per high-level feature ("create_deck", "publish_deck", "share_deck") is agent-hostile: every new feature request needs a new tool. A product that ships atomic primitives ("add_slide", "update_slide_content", "reorder_slides", "set_visibility") lets the agent compose new features by chaining primitives - no product change required.

The granularity test: could an agent build a feature you did not design by combining existing tools? If no, your tools are too coarse. If the agent must rebuild the same 4-step sequence over and over, you are missing a higher-level primitive. The goal is a balanced vocabulary where most novel workflows are expressible but the common case is concise.

Atomic does not mean trivial. A primitive is atomic when it does one thing the caller can reason about in isolation, returns a stable result, and does not bake in a specific higher-level workflow.

### 3. Composability

**New features become new prompts, not new code.**

When the agent has parity and granularity, a "feature" can often ship as a system prompt that guides the agent through an orchestration of existing primitives. The build queue for product work shrinks; the build queue for tools and primitives grows. You invest once in a durable surface, not repeatedly in one-off flows.

Composability is a culture shift as much as an architecture one. Before writing new feature code, ask: "Can this be a prompt over existing tools?" If yes, ship it as a prompt. Reserve code for new primitives the prompt cannot express.

This is the principle most often violated retroactively. Teams add tools, then when product asks for a complex feature, they add a specialized tool that duplicates logic instead of composing the atomic ones. Audit for duplication between tools - it signals a missed composition.

### 4. Emergent Capability

**The agent accomplishes things you did not design for.**

Parity + granularity + composability together produce a surface where the agent, handed a novel prompt, completes tasks the product team never imagined. A user asks "make the deck feel more playful and move the agenda to after the intro"; the agent reorders slides, rewrites copy, and adjusts theme tokens - all with the same primitives that exist for simpler flows.

Emergent capability is the payoff. You cannot ship it directly; you earn it by doing the first three principles well. When you see the agent solving tasks outside the product's explicit feature set, the architecture is working.

Measure it by tracking prompts that the agent satisfies without adding a new tool. High count = high emergence. Low count = the surface is not yet rich enough.

## Operating Guidance

### Design-time

- Start from tools, not UI. When adding a new capability, write the tool signature first. The UI is a specific client of the tool.
- Expose structured data, not presentation. The agent cannot parse `<div class="price">$12.99</div>`; it can use a `price: { amount: 12.99, currency: "USD" }` field.
- Prefer idempotent operations. `set_slide_title(id, "X")` is safer and more composable than `append_to_title(id, "X")`. The agent can retry without reasoning about prior state.
- Return rich results. A tool that returns `{ ok: true }` is less useful than one that returns the updated resource. The agent can chain without re-fetching.

### Runtime

- Errors are instructions. A tool that fails with `404 not found` is less useful than one that fails with `no slide with id "s12" - existing slide ids: [s1, s2, ... s8]`. The error should tell the agent what to try next.
- Log tool calls as product telemetry. The sequence of tools an agent invokes on a prompt is the product's new analytics surface.
- Gate destructive actions on confirmation tokens the agent can request, not on UI-only confirmations. The confirmation should be a parameter in a tool call, not a modal.

### Audit

- Count user actions. Count tools. Compute parity.
- Read a sample of tools for overlap. Overlap signals missed composition.
- Read tool responses for presentation leaks. Presentation in responses blocks composition.
- Look for recent features and ask whether each one shipped as new code or as a new prompt over existing tools. The trend line is the composability metric.

## Anti-Patterns

- **The Screen-Scraping Tool.** A "tool" that takes a URL and returns rendered HTML is not agent-native; it is a browser in disguise. Real tools expose structured state, not pixels.
- **The God Tool.** One tool with fifteen optional parameters that does "anything about a deck" is not atomic. Split it.
- **The UI-Only Confirmation.** "Are you sure?" modals that gate a destructive action and cannot be satisfied programmatically. Turn them into a `confirm: true` parameter or a two-step `prepare + commit` pair.
- **The Batched Workflow Tool.** A "publish_and_share_and_notify" tool that bundles three primitives. The agent cannot reuse any one of them; the bundle is an opinion frozen into the surface.
- **The Non-idempotent Mutator.** `increment_version()` instead of `set_version(n)`. The agent cannot safely retry.

## When to Apply These Principles

- Designing new product surfaces intended to be driven by an agent.
- Auditing an existing product whose team wants to add an "AI assistant" - the first question is whether the product is agent-native, not whether the assistant is well-prompted.
- Reviewing a pull request that adds a new feature to an agent-first application - use the principles as the review rubric.

## When NOT to Apply

- Internal admin tools with no agent consumers and no plan for one.
- Prototypes being thrown away.
- Surfaces where the security model explicitly excludes programmatic access.

In all three cases, the principles may still produce cleaner design, but the audit is not worth the cost.

rules/agent-native-self-eval.md

# Agent-Native Self-Eval / Red-Team Rubric

A repeatable rubric for evaluating whether a surface is genuinely agent-native and resilient. Use it to self-audit a system you built, to review one you inherited, or as a consistent scoring standard when assessing agentic engineering work. It operationalizes the four principles in `agent-native.md` (parity, granularity, composability, emergent capability) into a measurable pass/fail procedure backed by parallel red-team probing.

The format generalizes the Twitter-clone-for-agents pattern: build (or point at) a small social-feed system whose tools and surface satisfy the four principles, then dispatch N parallel red-team agents against the deployed surface. The system passes if no agent breaks it within a fixed budget and the parity/composability thresholds are met.

Principles referenced: `agent-native.md`.
Red-team dispatch: `subagent-patterns.md`.

---

## Part 1: The Reference Surface

A small social-feed system is the canonical test case. It is the test fixture, not a deliverable — you probe it, you do not ship it. The choice is deliberate: a social feed is small enough for 5-10 agents to exhaust in a fixed budget, complex enough to require all four principles, and generic enough that no domain knowledge advantages the builder.

### Minimum Surface (6 domains, 12 tools)

Every user-visible action must have a callable tool with identical semantics, identical permissions, and identical resulting state (parity principle). The minimum surface is:

| Domain | Tool | Description |
|--------|------|-------------|
| Posts | `post_create` | Create a new post with text content (max 280 chars). Returns the created post object including id, author_id, created_at, like_count, reply_count. |
| Posts | `post_delete` | Delete a post by id. Only the author or an admin can delete. Returns the deleted post id. |
| Replies | `reply_create` | Create a reply to a post or to another reply. Returns the reply object with parent_id set. |
| Replies | `reply_delete` | Delete a reply by id. Same auth rules as post_delete. |
| Reactions | `like_toggle` | Like or unlike a post or reply by id. Idempotent: calling like on an already-liked item returns the current state without error. Returns `{ liked: bool, like_count: int }`. |
| Social | `follow_toggle` | Follow or unfollow a user by id. Idempotent. Returns `{ following: bool, follower_count: int }`. |
| Feeds | `feed_own` | Return the authenticated user's posts, newest-first. Accepts `cursor` and `limit` (max 50, default 20). |
| Feeds | `feed_following` | Return posts from users the authenticated user follows. Same pagination contract as `feed_own`. |
| Feeds | `feed_public` | Return all posts, newest-first, no auth required. Same pagination. |
| Search | `search_posts` | Search posts and replies by keyword. Returns a ranked list with match highlights. Accepts `query`, `cursor`, `limit`. |
| Users | `user_get` | Get a user's public profile: username, bio, follower_count, following_count, post_count. |
| Auth | `session_create` | Create an authenticated session given credentials. Returns a session token for use in subsequent calls. |

The twelve tools above are the minimum. More are allowed (granularity: richer primitives enable more emergent behavior). Two must never be merged into a single batched tool (granularity violation).

### Surface Requirements

Beyond the tool list, the surface must satisfy:

1. **Parity**: Every action a user can take in any UI (if one exists) is covered by a tool.
2. **Granularity**: No tool does two things. No tool encodes a workflow. `post_create_and_follow_author` is a violation.
3. **Composability**: At least three documented example prompts that compose existing tools to produce a behavior the surface did not explicitly design for. Example: "Summarize the top-5 most-liked posts from the last 24 hours and reply to each with a one-sentence takeaway." The agent must complete this using only the twelve tools, no new code.
4. **Error messages are instructions**: Every tool failure must name the reason and suggest the next action. `{ error: "not_found", message: "post id 'p999' does not exist; use feed_public to find valid ids" }` is acceptable. `{ error: "500" }` is not.
5. **Idempotency**: `like_toggle` and `follow_toggle` must be safe to call twice in a row. `post_create` must not be idempotent (calling it twice creates two posts).
6. **No UI-only flows**: If a UI exists, every action in it must be reachable by a tool. Modal confirmations for destructive actions must be satisfiable programmatically (e.g., a `confirm: true` parameter on `post_delete`).

---

## Part 2: Red-Team Evaluation

### Setup

Dispatch N agents (default 5, maximum 10, configurable) in parallel. Each agent receives:
- The surface URL or the tool schema
- Its assigned attack category (see below)
- The budget: a fixed number of tool calls (default 200 per agent)
- The pass criterion: zero exploits means zero exploits

Dispatch follows the parallel research pattern in `subagent-patterns`: write a spec for each agent, dispatch simultaneously, aggregate results after all agents return. Do not dispatch agents sequentially.

Each agent runs in `mode:headless` and returns a structured envelope:

```
{
  "agent_id": "red-team-1",
  "category": "auth-bypass",
  "exploit_found": bool,
  "exploit_description": "string or null",
  "calls_used": int,
  "findings": ["list of non-exploit observations"]
}
```

### Attack Category Assignments (default 5 agents)

| Agent | Category | Focus |
|-------|----------|-------|
| 1 | Auth bypass | Can the agent access or mutate another user's posts, likes, follows, or session without valid credentials? Try `post_delete` on another user's post, `reply_create` without auth, `session_create` with invalid credentials that still returns a token. |
| 2 | Parity gap | Are there user-visible actions with no tool equivalent? Enumerate the UI surface (if any) and verify every action maps to a tool. Report any action without a tool as a parity gap. |
| 3 | Granularity violation | Are any tools doing two things? Call each tool and inspect the response shape. A tool that creates a post AND follows the author in a single call is a violation. |
| 4 | Injection and data integrity | Can the agent inject content that breaks other agents' tool calls? Long strings, special characters, SQL metacharacters, JSON-breaking characters in `post_create` text. Does `search_posts` return results that could be interpreted as tool instructions? |
| 5 | Emergent capability | Attempt 5 novel prompts that compose the twelve tools to produce behavior not explicitly designed. For each prompt, report whether the agent succeeded, which tools it used, and how many calls it required. This is the positive probe: the agent is trying to succeed, not break. |

### Scaling the Budget

For 5 agents at 200 calls each, total budget is 1,000 tool calls. Adjust proportionally:

| N agents | Calls per agent | Total budget |
|----------|----------------|--------------|
| 5 | 200 | 1,000 |
| 8 | 150 | 1,200 |
| 10 | 100 | 1,000 |

Fewer calls per agent with more agents favors breadth. More calls per agent with fewer agents favors depth. The default is 5 agents at 200 calls.

---

## Part 3: Scoring

### Pass Criteria (all must be met)

| Criterion | Threshold | How to measure |
|-----------|-----------|----------------|
| Zero exploits | 0 exploits across all red-team agents | Count `exploit_found: true` in agent envelopes |
| Parity score | >= 85% | `(tools covering user actions) / (total user-visible actions) * 100` |
| Emergent capability | >= 3 of 5 novel prompts succeed | Count successes from agent 5's findings |
| Granularity violations | 0 | Count violations from agent 3's findings |
| Error quality | 100% of sampled failures include reason + next action | Manual spot-check of 5 tool failures |

### Scoring Bands

| Score | Interpretation |
|-------|----------------|
| All criteria met | Pass: surface is agent-native and resilient |
| 1 criterion missed | Conditional pass: specific gap identified, fixable in one session |
| 2 criteria missed | Fail: surface needs redesign in the failing area |
| Exploit found | Hard fail: security issue must be resolved before re-evaluation |

### Scoring the Parity Audit

Parity score is a count, not an opinion. The evaluator must:

1. Enumerate every user-visible action (button, form submission, gesture with programmatic effect) in the surface. If there is no UI, the tool schema is the surface and parity is 100% by definition (but the six-domain minimum still applies).
2. Map each action to a tool. An action is covered if there is a tool with the same semantics.
3. Report `covered / total` as the parity score.

A parity score below 85% is a failing criterion. The gap list is the specific finding.

### Scoring Emergent Capability

Agent 5 attempts 5 novel prompts. Select prompts that:
- Require at least 3 tool calls in sequence
- Produce an outcome the surface did not explicitly design (no single tool does the full job)
- Are useful to a real user (not contrived)

Example prompts for a social feed:
1. "Find the 3 most-liked posts in the last hour and reply to each with a short summary."
2. "Follow every user who liked a specific post."
3. "Delete all my posts that received no likes within 24 hours of posting."
4. "Find all posts mentioning a keyword and like each one."
5. "Reply to the 5 most recent posts from users I follow with a fixed string."

A prompt succeeds if the agent completes it without error using only the twelve tools. A prompt fails if the agent cannot complete it or must make more than 50 calls (signal of surface brittleness).

---

## Part 4: Self-Evaluation (Without a Red-Team)

When red-team agents are not available (no budget, solo evaluation), use this abbreviated checklist:

**Parity checklist (manual)**
- [ ] List every action in your surface. Count them.
- [ ] For each action, name the tool that covers it. If no tool, note the gap.
- [ ] Compute `covered / total`. Target >= 85%.

**Granularity checklist (manual)**
- [ ] For each tool, write one sentence: "This tool does X and only X."
- [ ] If the sentence requires "and" to describe two separate effects, the tool is a violation.

**Composability checklist (manual)**
- [ ] Write 3 example prompts that chain 3+ tools.
- [ ] Execute each prompt against your live surface.
- [ ] If any prompt requires a tool that does not exist, the surface is not composable enough.

**Error quality checklist (manual)**
- [ ] Call each tool with invalid input (wrong id, missing field, wrong type).
- [ ] For each error response, confirm it names the reason and suggests a next step.

**Security checklist (manual)**
- [ ] Attempt `post_delete` on a post id that belongs to a different user. Confirm it fails with a permission error.
- [ ] Attempt `feed_following` without a session token. Confirm it fails with an auth error.
- [ ] Attempt `session_create` with a bad password. Confirm it returns an error and does not return a valid token.

---

## Notes on Scope

This rubric describes the evaluation format. It does not describe the implementation of the test surface. The builder implements the surface; the rubric tells them what it must satisfy and how it will be probed. The rubric is complete and useful as a self-eval standard even without automated red-team dispatch.

skill (1)

skills/agent-native-audit/SKILL.md

---
name: agent-native-audit
description: >
  Audit a codebase against the four agent-native principles (parity, granularity, composability, emergent capability) and return a scored report with concrete counts and fix recommendations. Dispatches eight parallel research subagents, two per principle, so one agent measures and one agent critiques. Use before shipping an agent-facing feature or when assessing whether a product is ready for an AI assistant layer.
  Triggers: agent-native audit, audit agents, audit for AI, score agent-friendliness, parity check, tool coverage audit.
disable-model-invocation: true
---

# /agent-native-audit - Agent-Native Architecture Audit

Score a codebase against the four agent-native principles defined in `modules/agent-native/rules/agent-native.md`. Produce a report with specific counts ("agent can do X of Y user actions"), named examples of violations, and concrete first-PR recommendations.

The report is the output. The skill does not modify code.

## When to Run

- Before adding an AI assistant, copilot, or "chat with the app" feature to an existing product.
- When designing the second or third major feature of an agent-first product (the first feature rarely needs the audit; the third reveals whether the foundation holds).
- As a quarterly check on a product marketed as agent-native.
- As a review step on a pull request that adds or modifies an agent tool surface.

Do NOT run for:

- Admin-only tooling with no agent consumers.
- Marketing sites, landing pages, or pure-content projects.
- Libraries and SDKs consumed only by human developers (the audit is for product surfaces, not code packages).

## Mode Selection

Parse `$ARGUMENTS` for a mode token (see `modules/subagent-patterns/rules/subagent-patterns.md` for the standard mode contract):

- `mode:full` (or no mode token) - eight parallel subagents, full scored report.
- `mode:report-only` - strictly read-only, no file writes even for the run artifact. Safe for concurrent runs.
- `mode:headless` - structured envelope output for skill-to-skill invocation (`/ce-review`, `/xplan`).

Full mode is the default. In full mode the skill writes a run artifact to `.agent-native-audit/{timestamp}.md` so the user can diff future runs.

## Inputs

If `$ARGUMENTS` contains a path, scope the audit to that directory. Otherwise the audit covers the repo root.

Optional steering in `$ARGUMENTS`:

- `focus:parity` / `focus:granularity` / `focus:composability` / `focus:emergent` - deep-dive one principle, skip the others.
- `baseline:{path}` - compare to a prior audit artifact, report deltas only.

## Phase 0: Codebase Triage

Before dispatching subagents, do a fast one-pass scan so each subagent starts from shared context:

1. Identify the tool/primitive surface. Common shapes:
   - MCP server registrations (`server.registerTool(...)`, `navigator.modelContext.registerTool(...)`)
   - tRPC / GraphQL / REST route handlers
   - Command or action dispatch tables
   - Redux / Zustand / Context actions that mutate global state

2. Identify the user-visible action surface. Common shapes:
   - Button `onClick` handlers in component files
   - Form `onSubmit` handlers
   - Keyboard shortcut tables
   - Router `POST` / `PATCH` / `DELETE` endpoints wired to UI flows

3. Write a short "Triage Notes" block to the run artifact:

   ```
   ## Triage
   - Tool surface: {count, location, framework}
   - User-action surface: {count, location, framework}
   - Primary entry points: {list}
   - Known agent consumers: {yes/no, names}
   ```

If the codebase has no identifiable tool surface (no MCP server, no agent-facing API), STOP and return:

```
Agent-native audit not applicable: no tool/primitive surface detected.
This audit scores products that expose tools to agents. The scanned code
appears to be {description}. If you intend this to be agent-native,
start by exposing a tool surface - see modules/agent-native/rules/agent-native.md
for design guidance.
```

## Phase 1: Parallel Analysis

Dispatch **eight agents in parallel** - two per principle. One agent per pair measures (counts, inventory); the other critiques (examples, violations, fixes). Use `subagent_type: "Explore"` and launch all eight in a single message so they run concurrently.

> **Concurrency — avoid the 429 throttle.** Eight light `Explore` agents is at the safe ceiling for a single parallel wave — acceptable because they are cheap and scoped. Do NOT raise the count, and if you ever switch them to a heavier model / higher reasoning effort, split into two sequential waves of 4 (measure pass, then critique pass). Bursting more than ~5 heavy agents — or many more light ones — trips a server-side rate limit (`Server is temporarily limiting requests · Rate limited`) that fails the whole dispatch; if you hit it, launch as 4+4. See `~/.claude/rules/concurrency-and-rate-limits.md`.

Pass paths, not file contents (see `modules/subagent-patterns/rules/subagent-patterns.md`). Each agent gets the triage summary, the principle text verbatim from `modules/agent-native/rules/agent-native.md`, and the scoped paths to analyze.

Every agent prompt must end with:

```
Return findings as the specified JSON object. Scope claims to what you
actually read; do not extrapolate from file names. End your report with
one of: DONE, DONE_WITH_CONCERNS, BLOCKED, NEEDS_CONTEXT.
```

### Agent 1A - Parity: Inventory

```
You are auditing {repo} for agent-native parity.

Principle: whatever a user can do in the UI, the agent can do via a tool.

Tasks:
1. Enumerate user-visible actions. Grep for onClick, onSubmit, form handlers,
   router POST/PATCH/DELETE handlers, keyboard shortcut tables. Produce a list.
2. Enumerate agent tools. Grep for the tool registration pattern identified
   in Phase 0 triage. Produce a list.
3. Attempt a pairwise mapping: for each user action, does a tool exist with
   the same semantics?

Return JSON:
{
  "user_actions": [{ "name": string, "file": string, "line": number }],
  "agent_tools": [{ "name": string, "file": string, "line": number }],
  "mapping": [{ "user_action": string, "tool": string | null }],
  "parity_ratio": "X of Y",
  "parity_percent": number
}
```

### Agent 1B - Parity: Violations

```
You are auditing {repo} for agent-native parity gaps.

Find the top 5 user actions that have no tool equivalent. For each, report:
- The user action (name, file, line)
- Why the gap matters (what outcome the agent cannot achieve)
- A proposed tool signature that would close the gap
- Estimated effort: trivial | moderate | significant

Return JSON:
{
  "top_gaps": [{
    "user_action": string,
    "file": string,
    "line": number,
    "why_matters": string,
    "proposed_tool": string,
    "effort": "trivial" | "moderate" | "significant"
  }]
}
```

### Agent 2A - Granularity: Primitive Inventory

```
You are auditing {repo} for agent-native granularity.

Principle: prefer atomic primitives. Features are outcomes an agent achieves
by composing primitives in a loop.

Tasks:
1. Classify each tool identified in Phase 0 as atomic | coarse | bundle.
   - atomic: one action, one resource, composable
   - coarse: accepts many optional parameters that change behavior modally
   - bundle: combines what should be two or more primitives
2. Identify primitives that appear to be missing - sequences of operations
   the agent would need to chain that no current tool supports.

Return JSON:
{
  "atomic_count": number,
  "coarse_count": number,
  "bundle_count": number,
  "examples": {
    "atomic": [string], "coarse": [string], "bundle": [string]
  },
  "missing_primitives": [{ "name": string, "rationale": string }]
}
```

### Agent 2B - Granularity: Critique

```
Find the top 3 granularity violations. For each, report:
- The tool name and signature
- Why it is too coarse or bundled
- A proposed refactor (split into N atomic tools, with signatures)
- A before/after sketch of how an agent would accomplish the same outcome

Return JSON:
{
  "violations": [{
    "tool": string,
    "category": "coarse" | "bundle",
    "why": string,
    "proposed_split": [string],
    "before_sketch": string,
    "after_sketch": string
  }]
}
```

### Agent 3A - Composability: Duplication Scan

```
You are auditing {repo} for composability.

Principle: new features become new prompts, not new code. Tool surfaces that
force teams to add a new tool per feature are not composable.

Tasks:
1. Scan tool implementations for duplicated logic. Two tools that call the
   same internal helper in the same way are candidates for composition.
2. Scan git history (last 90 days) for commits that added a new tool. For
   each, note whether the feature could plausibly have been a prompt over
   existing tools.

Return JSON:
{
  "duplication_pairs": [{ "tool_a": string, "tool_b": string, "shared_logic": string }],
  "recent_additions": [{
    "tool": string,
    "commit": string,
    "could_have_been_prompt": boolean,
    "reasoning": string
  }]
}
```

### Agent 3B - Composability: Critique

```
Identify the single highest-leverage composition opportunity - a set of
existing tools that, with one refactor or one new atomic primitive, would
eliminate a recurring need to add specialized tools.

Return JSON:
{
  "opportunity": {
    "current_tools": [string],
    "refactor_or_new_primitive": string,
    "unlocks": string,
    "effort": "trivial" | "moderate" | "significant",
    "expected_impact": string
  }
}
```

### Agent 4A - Emergent Capability: Evidence

```
You are auditing {repo} for emergent capability.

Principle: a mature agent-native surface lets the agent accomplish tasks the
product team did not explicitly design for.

Tasks:
1. Look for evidence in agent logs, session history, or test prompts of the
   agent solving tasks that map to no single tool. Common signals: a user
   prompt in the test suite that exercises a chain of 3+ tools.
2. Look for product tickets or issue comments that describe "the agent
   figured out how to do X" or similar.

If the repo has no such evidence, say so - this principle is the last to
mature and absence is expected in young products.

Return JSON:
{
  "evidence_found": boolean,
  "examples": [{ "task": string, "tools_chained": [string], "source": string }],
  "maturity_signal": "absent" | "early" | "established"
}
```

### Agent 4B - Emergent Capability: Recommendations

```
Based on the parity, granularity, and composability findings, name the two
or three prompts a team could try right now that would surface whether
emergent capability exists or not.

Return JSON:
{
  "probe_prompts": [{
    "prompt": string,
    "expected_tools_chained": [string],
    "success_criterion": string
  }]
}
```

## Phase 2: Score and Synthesize

Merge the eight reports into a single scorecard. Each principle scores 0 to 25, for a total of 100.

```
## Score

| Principle | Score | Band |
|---|---|---|
| Parity | {N}/25 | {band} |
| Granularity | {N}/25 | {band} |
| Composability | {N}/25 | {band} |
| Emergent Capability | {N}/25 | {band} |
| **Total** | **{N}/100** | **{band}** |

Bands: 0-10 absent, 11-17 emerging, 18-22 solid, 23-25 exemplary.
```

### Scoring Rubric

- **Parity**: map `parity_percent` to 0-25. 100% -> 25, 80% -> 20, 50% -> 12, 0% -> 0.
- **Granularity**: start at 25, subtract 2 per coarse tool, 4 per bundle tool, floor at 0.
- **Composability**: start at 25, subtract 2 per duplication pair, 3 per "could_have_been_prompt" commit, floor at 0.
- **Emergent Capability**: `absent` = 0, `early` = 12, `established` = 20, plus up to 5 bonus for multiple distinct emergent examples.

## Phase 3: Top-5 Findings and Recommendations

After the scorecard, write a Top-5 Findings section. Each finding has:

- **Principle** (one of the four)
- **Finding** (one sentence)
- **Evidence** (file:line references from agent reports)
- **Impact** (what the agent cannot do because of this)
- **Fix** (concrete first PR, effort-sized trivial/moderate/significant)

Prefer findings that are concrete, cheap, and visible to the agent. A trivial parity fix beats a significant emergent-capability plan in almost every case.

## Phase 4: Output

### Full mode

Write the full report to `.agent-native-audit/{YYYY-MM-DD-HHmm}.md` and print it to the user. If a prior audit exists, include a "Delta vs {prior date}" block at the top.

### Report-only mode

Print the full report. Do not write any files.

### Headless mode

Emit a structured envelope:

```
<<<AUDIT_REPORT_JSON>>>
{
  "total_score": number,
  "scores": { "parity": number, "granularity": number, "composability": number, "emergent": number },
  "top_findings": [{ ... }],
  "probe_prompts": [{ ... }]
}
<<<END_AUDIT_REPORT_JSON>>>
```

Then a one-line terminal: `Audit complete.`

## Guardrails

- Do not modify application code. This skill writes only to `.agent-native-audit/` (in full mode).
- Do not extrapolate from file names. Claims must be backed by a subagent's file:line evidence.
- Do not score principles the codebase cannot support. If there is no tool surface, the audit is not applicable (see Phase 0 stop condition).
- Preserve the four-state status protocol (DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT) at the end of every subagent report and at the end of the skill's own final message.

## Related

- `modules/agent-native/rules/agent-native.md` - the four principles this skill audits against.
- `modules/subagent-patterns/rules/subagent-patterns.md` - the pass-paths-not-contents and skill-mode conventions this skill uses.
- `modules/agent-native/agents/reviewers/agent-native-reviewer.md` - the persona for when this skill is invoked as one lens inside a broader `/ce-review` orchestration.

agent (1)

agents/reviewers/agent-native-reviewer.md

---
name: agent-native-reviewer
description: >
Review a pull request or codebase slice through the agent-native lens - parity, granularity, composability, emergent capability. Returns a structured critique with specific file:line references. Invoked as one reviewer inside the unified review orchestrator (see CCGM #277). Can also run standalone against a diff.
tools: Glob, Grep, Read, Bash
---

# agent-native-reviewer

Review code changes against the four agent-native principles and return a structured critique that the caller can merge with other reviewer outputs. The persona is a senior architect of agent-first applications who treats the tool surface as the real product.

This agent does **not** propose speculative features. It evaluates the concrete change in front of it and flags places the change weakens or strengthens agent-nativeness.

## Inputs

The caller passes:

- `diff` (required) - unified diff or list of changed files with a summary
- `repo_path` (required) - absolute path to the repo so Grep/Read can work
- `focus` (optional) - `parity`, `granularity`, `composability`, `emergent`, or `all` (default)
- `prior_audit` (optional) - path to a prior `.agent-native-audit/*.md` artifact for baseline

## Discovery

1. Read the diff. Classify each changed file as:

- **Tool surface** - registers, implements, or modifies an agent-callable tool
- **UI surface** - user-visible component, page, or route
- **Shared logic** - helpers, services, models that both surfaces depend on
- **Infra** - build, CI, config (not reviewed by this persona)

2. If the diff touches only infra, return `not_applicable: "no agent-visible surface in diff"` and stop.

3. If `prior_audit` is set, load the prior scores to compare against.

## Review Lenses

For each of the four principles, apply the corresponding lens. Skip lenses that `focus` excludes.

### Parity lens

- Does the diff add a user action? If yes, does it also add (or wire up) an agent-callable tool with the same semantics?
- Does the diff add a tool? If yes, does the tool have the same permissions and side effects as the UI-equivalent action (or explicit justification for the divergence)?
- Does the diff remove a tool while preserving the UI action? That is a parity regression.

### Granularity lens

- Does the diff add a new tool that could have been composed from existing atomic tools? Flag it.
- Does the new tool accept optional parameters that change its behavior modally? Flag it.
- Does the new tool bundle multiple distinct outcomes in one call? Flag it.
- Conversely, does the diff refactor a coarse tool into atomic primitives? Praise it.

### Composability lens

- Does the new tool share logic with an existing tool? If yes, is the shared logic extracted into a helper, or duplicated?
- Does the change add a code path that could have been a system prompt over existing tools? Flag it.
- Does the change extract shared logic that enables future composition? Praise it.

### Emergent Capability lens

- Does the diff expose new structured data that unblocks tasks the product did not explicitly design for? Note it.
- Does the diff narrow a tool's surface in a way that blocks plausible emergent uses? Flag it.
- Does the diff add a probe-style test (a prompt that chains 3+ tools) validating emergent capability? Praise it.

## Output

Return a structured critique block:

```
### Agent-Native Review

**Verdict:** approve | approve-with-concerns | request-changes

**Principle scores (deltas vs prior audit if provided):**
- Parity: {+N | -N | 0}
- Granularity: {+N | -N | 0}
- Composability: {+N | -N | 0}
- Emergent Capability: {+N | -N | 0}

**Findings:**

1. [Principle] - {one-sentence finding}
- Evidence: {file:line}
- Impact: {what the agent can or cannot do}
- Suggestion: {concrete change}

2. ...

**Praise (if any):**
- {file:line}: {what the change does well}

**Summary:**
{two or three sentences on the overall direction}
```

End with one of the four-state status tokens: `DONE`, `DONE_WITH_CONCERNS`, `BLOCKED`, `NEEDS_CONTEXT`.

## Guardrails

- Never propose a refactor that expands the diff beyond the current change's scope. Flag the issue; the caller decides whether to fix now or later.
- Never score absolute numbers. Return deltas only. The audit skill scores absolutes; this reviewer scores change.
- Never request stylistic changes unrelated to the four principles. Other reviewers cover prose, security, tests, etc.
- Never rely on file names alone. Every finding needs a `file:line` pointer the caller can verify.

## When to Invoke

- From the unified review orchestrator (CCGM #277) as one of several reviewer personas.
- Standalone on a diff with `git diff origin/main...HEAD | <this agent>`.
- As part of a codebase spot-check before merging a feature that shifts the tool surface.

See `modules/agent-native/rules/agent-native.md` for the full principles and `modules/agent-native/skills/agent-native-audit/SKILL.md` for the full-codebase scoring skill this reviewer complements.

View source on GitHub

Tags

README

Agent-Native Architecture

The Four Principles

What This Module Provides

Manual Installation

Usage

Audit a codebase

Review a diff

Self-eval / red-team a surface

Use the rule as design guidance

Dependencies

Non-Goals

Source

Will install

Dependencies

Required by

Included in presets

Install this module

Agent prompt

Native plugin marketplace

Manual, per file

Files

rules/agent-native.md

rules/agent-native-self-eval.md

skills/agent-native-audit/SKILL.md

agents/reviewers/agent-native-reviewer.md