lets-agent-native-architecture

## Agent-Native Architecture

Agent-native applications treat agents as first-class citizens. Features are outcomes achieved by an agent with tools operating in a loop, not functions written in code. The same architecture that powers Claude Code can power apps far beyond coding.

Five core principles:

1. Parity — Whatever the user can do through the UI, the agent can achieve through tools.
2. Granularity — Tools are atomic primitives; features are prompt-defined outcomes. To change behavior, edit prose, not code.
3. Composability — New features = new prompts, not new code. Atomic tools + parity make this possible.
4. Emergent Capability — The agent accomplishes things you didn't explicitly design for. Open-ended requests reveal latent demand.
5. Improvement Over Time — Apps get better through accumulated context (e.g. a context.md file) and prompt refinement, without shipping code.

For deep coverage of how these principles translate into architectural patterns, read references/architecture-patterns.md.

## What aspect of agent-native architecture do you need help with?

1. Design architecture - Plan a new agent-native system from scratch
2. Files & workspace - Files as universal interface, shared workspace patterns
3. Tool design - Primitive tools, dynamic capability discovery, CRUD completeness
4. Domain tools - When to add domain tools vs stay with primitives
5. Execution patterns - Completion signals, partial completion, context limits
6. System prompts - Define agent behavior, 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. Review / checklists - Architecture checklist, anti-patterns, success criteria

Pick a number or describe what you want. Wait for the response before proceeding.

| Response | Read | |----------|------| | 1, "design", "architecture", "plan" | `references/architecture-patterns.md`, then apply the checklist in `references/checklists.md` | | 2, "files", "workspace", "filesystem" | `references/files-universal-interface.md` and `references/shared-workspace-architecture.md` | | 3, "tool", "mcp", "primitive", "crud" | `references/mcp-tool-design.md` | | 4, "domain tool", "when to add" | `references/from-primitives-to-domain-tools.md` | | 5, "execution", "completion", "loop" | `references/agent-execution-patterns.md` | | 6, "prompt", "system prompt", "behavior" | `references/system-prompt-design.md` | | 7, "context", "inject", "runtime", "dynamic" | `references/dynamic-context-injection.md` | | 8, "parity", "ui action", "capability map" | `references/action-parity-discipline.md` | | 9, "self-modify", "evolve", "git" | `references/self-modification.md` | | 10, "product", "progressive", "approval", "latent demand" | `references/product-implications.md` | | 11, "mobile", "ios", "android", "background", "checkpoint" | `references/mobile-patterns.md` | | 12, "test", "testing", "verify", "validate" | `references/agent-native-testing.md` | | 13, "refactor", "existing", "migrate" | `references/refactoring-to-prompt-native.md` | | 14, "review", "audit", "anti-pattern", "checklist", "success criteria" | `references/checklists.md` |

After reading the reference, apply those patterns to the user's specific context.

<reference_index>

Reference Files

Core patterns:

• references/architecture-patterns.md — Event-driven, unified orchestrator, agent-to-UI; full coverage of the five principles
• references/files-universal-interface.md — Why files, organization, context.md
• references/mcp-tool-design.md — Tool design, dynamic capability discovery, CRUD
• references/from-primitives-to-domain-tools.md — When to graduate primitives to domain tools
• references/agent-execution-patterns.md — Completion signals, partial completion, context limits
• references/system-prompt-design.md — Features as prompts, judgment criteria

Disciplines:

• references/dynamic-context-injection.md — Runtime context injection
• references/action-parity-discipline.md — Capability mapping, parity workflow
• references/shared-workspace-architecture.md — Shared data space, UI integration
• references/product-implications.md — Progressive disclosure, latent demand, approval
• references/agent-native-testing.md — Testing outcomes, parity tests
• references/checklists.md — Architecture checklist, anti-patterns, success criteria

Platform-specific:

• references/mobile-patterns.md — iOS storage, checkpoint/resume, cost awareness
• references/self-modification.md — Git-based evolution, guardrails
• references/refactoring-to-prompt-native.md — Migrating existing code </reference_index>