luokai0 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
- Design architecture - Plan a new agent-native system from scratch
- Files & workspace - Use files as the universal interface, shared workspace patterns
- Tool design - Build primitive tools, dynamic capability discovery, CRUD completeness
- Domain tools - Know when to add domain tools vs stay with primitives
- Execution patterns - Completion signals, partial completion, context limits
- System prompts - Define agent behavior in prompts, judgment criteria
- Context injection - Inject runtime app state into agent prompts
- Action parity - Ensure agents can do everything users can do
- Self-modification - Enable agents to safely evolve themselves
- Product design - Progressive disclosure, latent demand, approval patterns
- Mobile patterns - iOS storage, background execution, checkpoint/resume
- Testing - Test agent-native apps for capability and parity
- Refactoring - Make existing code more agent-native
- Anti-patterns - Common mistakes and how to avoid them
- Success criteria - Verify your architecture is agent-native
- 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, notz.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_tasktool (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_contexttool) - 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.