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.

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
17. CLI interface - Design a CLI that agents invoke: output channels, exit codes, self-description, safety tiers
18. 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

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.