What It Does
Codifies the five principles that distinguish "agent-native" architecture
from "agent-as-afterthought" — the patterns the
yellow-review:review:agent-native-reviewer agent checks against. This skill
is the canonical reference; the reviewer agent applies it.
When to Use
- Authoring or modifying agent tool definitions, system prompt construction,
or LLM-integration scaffolding.
- Designing a feature where users and agents will both act on shared data.
- Evaluating whether a UI action has a corresponding agent capability.
- Deciding whether a tool should be a primitive or a workflow.
Usage
The Five Principles
Action Parity — Every UI action has an equivalent agent tool. If a
user can rename a project via a button, the agent must have a
rename_project tool. Exceptions are intentional human-only flows
(CAPTCHA, 2FA, OAuth consent, biometric auth) and purely cosmetic UI
(animations, theme toggling).
Context Parity — Agents see the same data users see. The system
prompt must include available resources (files, entities, recent
activity), capability mappings (which tool does what), and domain
vocabulary. Static system prompts that don't reflect runtime state
produce agents that don't know what exists.
Shared Workspace — Agents and users operate in the same data space.
Agent file operations use the same paths as the UI; the UI observes
changes the agent makes (via shared store, file watching, or reactive
binding). Anti-pattern: agent writes to agent_output/ while user works
in documents/ — separate sandboxes break collaboration.
Primitives over Workflows — Tools are composable primitives whose
inputs are data, not decisions. A store_item(key, value) tool is
correct; a process_feedback(message) tool that internally categorizes
- prioritizes + notifies is a workflow tool that strips the agent of
reasoning agency.
Exception: Workflow tools are acceptable when they wrap
safety-critical atomic sequences (a payment must charge + record +
receipt as one unit) or external orchestration the agent shouldn't
step-through (a deploy tool).
Dynamic Context Injection — System prompts include runtime app
state, not just static instructions. The prompt at build-time names
the agent's role; the prompt at request-time names the user's current
project, recent files, available entities, and which capabilities apply
to this specific call.
The Noun Test
For every domain noun in the app (project, document, task, message,
report — whatever the entities are), verify the agent can:
- Know what it is — domain vocabulary in the system prompt
- Interact with it — at least one tool whose target is this noun
- Discover the capability — the tool is named in the prompt or
surfaced in onboarding
A noun that fails all three is a critical gap for must-have entities.
Anti-Pattern Catalog
| Anti-Pattern |
Signal |
Fix |
| Orphan Feature |
UI action with no agent tool |
Add tool; document in prompt |
| Context Starvation |
Agent unaware of resources or terms |
Inject resources + vocabulary into prompt |
| Sandbox Isolation |
Agent reads/writes separate data space |
Use shared workspace |
| Silent Action |
Agent mutates state, UI doesn't update |
Reactive binding or file watching |
| Capability Hiding |
Users can't discover agent capabilities |
Surface in agent responses |
| Workflow Tool |
Tool encodes business logic |
Extract primitives; orchestrate in prompt |
| Decision Input |
Tool accepts decision enum |
Accept data; let agent decide |
Priority Tiers
Not every gap is equal — prioritize findings by impact:
- Must have parity: Core domain CRUD, primary user workflows, actions
that modify user data.
- Should have parity: Secondary features, read-only views with
filtering/sorting.
- Low priority: Settings/preferences UI, onboarding wizards, admin
panels, purely cosmetic actions.
Critical findings only apply to must-have and should-have tiers; low-priority
gaps are observations.
Stack-Specific Tool Locations
| Stack |
Agent tools live at |
| Vercel AI SDK (Next.js) |
tool() in route handlers; tools param in streamText/generateText |
| LangChain / LangGraph |
@tool decorators; StructuredTool subclasses |
| OpenAI Assistants |
tools array in assistant config |
| Claude Code plugins |
agents/*.md, skills/*/SKILL.md, tool lists in frontmatter |
| Rails + MCP |
tool() in MCP server definitions; .mcp.json |
| Generic |
tool(, function_call, tools:, tool registration patterns |
What This Skill Doesn't Cover
- CLI agent-readiness — see
yellow-review:review:cli-readiness-reviewer
and yellow-review:review:agent-cli-readiness-reviewer for CLI-specific
agent optimization (non-interactive defaults, structured output, etc.).
- Agent authoring conventions — see
yellow-core:create-agent-skills for how to write Claude Code agents and
skills.
- MCP integration patterns — see
yellow-core:mcp-integration-patterns
for ruvector and morph integration patterns.
1---2name: agent-native-architecture-23description: Reference for agent-native architecture principles: action parity, context parity, shared workspace, primitives over workflows, and dynamic context injection. Use when authoring agent integrations or designing tool surfaces.4---56## What It Does78Codifies the five principles that distinguish "agent-native" architecture9from "agent-as-afterthought" — the patterns the10`yellow-review:review:agent-native-reviewer` agent checks against. This skill11is the canonical reference; the reviewer agent applies it.1213## When to Use1415- Authoring or modifying agent tool definitions, system prompt construction,16 or LLM-integration scaffolding.17- Designing a feature where users and agents will both act on shared data.18- Evaluating whether a UI action has a corresponding agent capability.19- Deciding whether a tool should be a primitive or a workflow.2021## Usage2223### The Five Principles24251. **Action Parity** — Every UI action has an equivalent agent tool. If a26 user can rename a project via a button, the agent must have a27 `rename_project` tool. Exceptions are intentional human-only flows28 (CAPTCHA, 2FA, OAuth consent, biometric auth) and purely cosmetic UI29 (animations, theme toggling).30312. **Context Parity** — Agents see the same data users see. The system32 prompt must include available resources (files, entities, recent33 activity), capability mappings (which tool does what), and domain34 vocabulary. Static system prompts that don't reflect runtime state35 produce agents that don't know what exists.36373. **Shared Workspace** — Agents and users operate in the same data space.38 Agent file operations use the same paths as the UI; the UI observes39 changes the agent makes (via shared store, file watching, or reactive40 binding). Anti-pattern: agent writes to `agent_output/` while user works41 in `documents/` — separate sandboxes break collaboration.42434. **Primitives over Workflows** — Tools are composable primitives whose44 inputs are data, not decisions. A `store_item(key, value)` tool is45 correct; a `process_feedback(message)` tool that internally categorizes46 + prioritizes + notifies is a workflow tool that strips the agent of47 reasoning agency.4849 **Exception:** Workflow tools are acceptable when they wrap50 safety-critical atomic sequences (a payment must charge + record +51 receipt as one unit) or external orchestration the agent shouldn't52 step-through (a deploy tool).53545. **Dynamic Context Injection** — System prompts include runtime app55 state, not just static instructions. The prompt at build-time names56 the agent's role; the prompt at request-time names the user's current57 project, recent files, available entities, and which capabilities apply58 to this specific call.5960### The Noun Test6162For every domain noun in the app (project, document, task, message,63report — whatever the entities are), verify the agent can:64651. **Know what it is** — domain vocabulary in the system prompt662. **Interact with it** — at least one tool whose target is this noun673. **Discover the capability** — the tool is named in the prompt or68 surfaced in onboarding6970A noun that fails all three is a critical gap for must-have entities.7172### Anti-Pattern Catalog7374| Anti-Pattern | Signal | Fix |75|---|---|---|76| Orphan Feature | UI action with no agent tool | Add tool; document in prompt |77| Context Starvation | Agent unaware of resources or terms | Inject resources + vocabulary into prompt |78| Sandbox Isolation | Agent reads/writes separate data space | Use shared workspace |79| Silent Action | Agent mutates state, UI doesn't update | Reactive binding or file watching |80| Capability Hiding | Users can't discover agent capabilities | Surface in agent responses |81| Workflow Tool | Tool encodes business logic | Extract primitives; orchestrate in prompt |82| Decision Input | Tool accepts decision enum | Accept data; let agent decide |8384### Priority Tiers8586Not every gap is equal — prioritize findings by impact:8788- **Must have parity:** Core domain CRUD, primary user workflows, actions89 that modify user data.90- **Should have parity:** Secondary features, read-only views with91 filtering/sorting.92- **Low priority:** Settings/preferences UI, onboarding wizards, admin93 panels, purely cosmetic actions.9495Critical findings only apply to must-have and should-have tiers; low-priority96gaps are observations.9798### Stack-Specific Tool Locations99100| Stack | Agent tools live at |101|---|---|102| Vercel AI SDK (Next.js) | `tool()` in route handlers; `tools` param in `streamText`/`generateText` |103| LangChain / LangGraph | `@tool` decorators; `StructuredTool` subclasses |104| OpenAI Assistants | `tools` array in assistant config |105| Claude Code plugins | `agents/*.md`, `skills/*/SKILL.md`, tool lists in frontmatter |106| Rails + MCP | `tool()` in MCP server definitions; `.mcp.json` |107| Generic | `tool(`, `function_call`, `tools:`, tool registration patterns |108109### What This Skill Doesn't Cover110111- **CLI agent-readiness** — see `yellow-review:review:cli-readiness-reviewer`112 and `yellow-review:review:agent-cli-readiness-reviewer` for CLI-specific113 agent optimization (non-interactive defaults, structured output, etc.).114- **Agent authoring conventions** — see115 `yellow-core:create-agent-skills` for how to write Claude Code agents and116 skills.117- **MCP integration patterns** — see `yellow-core:mcp-integration-patterns`118 for ruvector and morph integration patterns.
kinginyellows