Agent-Native Architecture
Working rules
- Keep authority, scope, approval, and runtime isolation in trusted orchestration; prompts alone cannot enforce them.
- Provide explicit completion and partial-progress signals, durable state, and observable action results.
- Validate capabilities with real tasks, including failure and interruption paths; do not infer improvement from elapsed usage.
- Evaluate discovery from original inputs. Replaying fixed candidates measures classification and cannot reveal candidates a changed search would miss or invent. Compare each discovery variant with a fresh baseline on the same complete inputs in isolation. Independently adjudicate unmatched outputs from the complete result sets, including outputs from clean tasks.
- Calibrate decision gates per model. A replacement model's confidence scores do not preserve the previous model's cutoff, even when ranking accuracy improves. Fit thresholds on a separate calibration set. Verify false-positive and false-negative behavior through the production decision path on untouched representative cases.
- Use the selected topic's references and the architecture checklist to produce a concrete design with evidence and unresolved constraints.
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 | Changing behavior means editing prose, not refactoring code |
| Composability | Can a feature be added by writing a new prompt, without new code? |
| Emergent Capability | Can the agent handle open-ended requests it wasn't designed 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
- CLI interface - Design a CLI that agents invoke: output channels, exit codes, self-description, safety tiers
- Approval loop - Durable human approval for agent-drafted external sends: content binding, single-winner claim, unknown outcomes
Route directly when the request or delegated task identifies the topic. When a material focus remains unresolved, present the relevant options using AskUserQuestion in Claude Code (load it with ToolSearch if needed), request_user_input in Codex, or numbered options in chat when no question tool is available. Wait only for the answer needed to resolve that choice.
Reference Routing
| Response | Action |
|---|---|
| 1, "design", "architecture", "plan" | Read architecture-patterns.md, then apply architecture-review-checklist.md |
| 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", "permissionDecision" | Read hooks-patterns.md |
| 17, "cli", "command line", "stdout", "exit code", "--format", "--dry-run" | Read cli-agent-interface.md |
| 18, "approval", "approve before send", "outbound", "ledger", "double-send" | Read operator-approval-loop.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.
Task-specific references
Read the relevant reference before implementing or reviewing the matching behavior:
- Before implementing an agent-native architecture, address every applicable architecture checklist item: architecture-review-checklist.md.
Existing specialized references, when the corresponding topic applies:
- durability-and-attestation.md.
- For controlled evaluations of hooks, skills, or prompt rules, read intervention-evaluation.md.