ia-agent-native-architecture

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.
• 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.

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