ia-agent-native-architecture

Agent-Native Architecture

Core Principles

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

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

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 its 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 the plan.