ia-agent-native-architecture

---

name: ia-agent-native-architecture class: meta description: >- Design agent-native applications where agents replace UI users as the primary actor. Use when designing MCP tools, agent-loop architectures, shared-workspace file patterns, or self-modifying agent systems.

---

Agent-Native Architecture

Core Principles

Five principles govern agent-native design. For detailed explanations, examples, and test criteria, see core-principles.md.

| Principle | One-line test | |-----------|--------------| | Parity | Can the agent achieve every outcome the UI allows? | | Granularity | To change behavior, do you edit prose or refactor code? | | Composability | Can you add a feature by writing a new prompt, without new code? | | Emergent Capability | Can the agent handle open-ended requests you didn't design for? | | Improvement Over Time | Does the app work better after a month, even without code changes? |

Focus Area Selection

1. Design architecture - Plan a new agent-native system from scratch 2. Files & workspace - Use files as the universal interface, shared workspace patterns 3. Tool design - Build primitive tools, dynamic capability discovery, CRUD completeness 4. Domain tools - Know when to add domain tools vs stay with primitives 5. Execution patterns - Completion signals, partial completion, context limits 6. System prompts - Define agent behavior in prompts, judgment criteria 7. Context injection - Inject runtime app state into agent prompts 8. Action parity - Ensure agents can do everything users can do 9. Self-modification - Enable agents to safely evolve themselves 10. Product design - Progressive disclosure, latent demand, approval patterns 11. Mobile patterns - iOS storage, background execution, checkpoint/resume 12. Testing - Test agent-native apps for capability and parity 13. Refactoring - Make existing code more agent-native 14. Anti-patterns - Common mistakes and how to avoid them 15. Success criteria - Verify your architecture is agent-native 16. Hooks patterns - Hook events, decision control, MCP matchers, async hooks

Wait for response before proceeding.

Reference Routing

| Response | Action | |----------|--------| | 1, "design", "architecture", "plan" | Read architecture-patterns.md, then apply Architecture Checklist below | | 2, "files", "workspace", "filesystem" | Read files-universal-interface.md and shared-workspace-architecture.md | | 3, "tool", "mcp", "primitive", "crud" | Read mcp-tool-design.md | | 4, "domain tool", "when to add" | Read from-primitives-to-domain-tools.md | | 5, "execution", "completion", "loop" | Read agent-execution-patterns.md | | 6, "prompt", "system prompt", "behavior" | Read system-prompt-design.md | | 7, "context", "inject", "runtime", "dynamic" | Read dynamic-context-injection.md | | 8, "parity", "ui action", "capability map" | Read action-parity-discipline.md | | 9, "self-modify", "evolve", "git" | Read self-modification.md | | 10, "product", "progressive", "approval", "latent demand" | Read product-implications.md | | 11, "mobile", "ios", "android", "background", "checkpoint" | Read mobile-patterns.md | | 11a, "icloud", "storage", "documents", "file state", "entitlement" | Read mobile-storage.md | | 11b, "background task", "battery", "on-device", "cloud routing" | Read mobile-execution.md | | 11c, "model tier", "token budget", "cost-aware", "batch", "caching" | Read mobile-cost.md | | 12, "test", "testing", "verify", "validate" | Read agent-native-testing.md | | 13, "review", "refactor", "existing" | Read refactoring-to-prompt-native.md | | 14, "anti-pattern", "mistake", "wrong" | Read anti-patterns.md | | 15, "success", "criteria", "verify", "checklist" | Read success-criteria.md | | 16, "hook", "hooks", "PreToolUse", "decision control", "async hook" | Read hooks-patterns.md | | 0, "quick start", "getting started", "overview", "introduction" | Read quick-start.md |

After reading the reference, apply those patterns to the user's specific context.

Architecture Review Checklist

When designing an agent-native system, verify these before implementation:

Core Principles

[ ] Parity: Every UI action has a corresponding agent capability

[ ] Granularity: Tools are primitives; features are prompt-defined outcomes

[ ] Composability: New features can be added via prompts alone

[ ] Emergent Capability: Agent can handle open-ended requests in your domain

Tool Design

[ ] Dynamic vs Static: For external APIs where agent should have full access, use Dynamic Capability Discovery

[ ] CRUD Completeness: Every entity has create, read, update, AND delete

[ ] Primitives over Workflows: Tools expose atomic capabilities; compose workflows in prompts

[ ] API as Validator: Use z.string() inputs when the API validates, not z.enum()

[ ] Eval Gate: 10 Q/A pairs in CI (read-only, multi-hop, closed-data), 9/10 pass threshold. See mcp-tool-design.md Evaluation section.

Files & Workspace

[ ] Shared Workspace: Agent and user work in same data space

[ ] context.md Pattern: Agent reads/updates context file for accumulated knowledge

[ ] File Organization: Entity-scoped directories with consistent naming

[ ] Context Durability: Incremental progress writes (WAL pattern) so interrupted tasks resume from last checkpoint

Agent Execution

[ ] Completion Signals: Agent has explicit complete_task tool (not heuristic detection)

[ ] Partial Completion: Multi-step tasks track progress for resume

[ ] Context Limits: Designed for bounded context from the start

[ ] Validate-Before-Run: Agent previews planned actions before executing destructive operations

Context Injection

[ ] Available Resources: System prompt includes what exists (files, data, types)

[ ] Available Capabilities: System prompt documents tools with user vocabulary

[ ] Dynamic Context: Context refreshes for long sessions (or provide refresh_context tool)

[ ] Trust levels for loaded content: System prompt distinguishes trusted (developer-authored) from untrusted (user input, retrieved docs, tool outputs); untrusted text is data, never instructions. See dynamic-context-injection.md Trust Levels section for the prompt-injection defense details.

UI Integration

[ ] Agent -> UI: Agent changes reflect in UI (shared service, file watching, or event bus)

[ ] No Silent Actions: Agent writes trigger UI updates immediately

[ ] Capability Discovery: Users can learn what agent can do

Governance

[ ] Approval Gates: Destructive or irreversible actions require user confirmation

[ ] Audit Trail: Agent actions logged with timestamp, tool, and outcome

[ ] Scope Boundaries: Agent cannot access resources outside its designated workspace

Hooks & Governance Automation

[ ] Event Coverage: Only 6 hook events fire in agent context (PreToolUse, PostToolUse, PermissionRequest, PostToolUseFailure, Stop/SubagentStop); session lifecycle logic lives in the orchestrator

[ ] Decision Gates: PreToolUse hooks enforce tool-level policy (allow/deny/ask/defer) instead of hardcoded checks

[ ] Completion Gating: SubagentStop hooks block premature completion when verification steps remain

[ ] MCP Matchers: Regex patterns target tools by server and operation for capability-based security

[ ] Two-Tier Config: Shared policy committed, personal overrides git-ignored, per-hook disable toggles

Mobile (if applicable)

[ ] Checkpoint/Resume: Handle iOS app suspension gracefully

[ ] iCloud Storage: iCloud-first with local fallback for multi-device sync

[ ] Cost Awareness: Model tier selection (Haiku/Sonnet/Opus)

When designing architecture, explicitly address each checkbox in your plan.