Skill: iliaal/compound-eng-agent-native-architecture (version 3.0.5)

--- name: ia-agent-native-architecture class: meta description: >- Design agent-native applications where agents replace UI users as the primary actor. Use when designing MCP tools, agent-loop architectures, shared-workspace file patterns, or self-modifying agent systems. --- # Agent-Native Architecture ## Core Principles Five principles govern agent-native design. For detailed explanations, examples, and test criteria, see [core-principles.md](./references/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 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 **Wait for response before proceeding.** ## Reference Routing | Response | Action | |----------|--------| | 1, "design", "architecture", "plan" | Read [architecture-patterns.md](./references/architecture-patterns.md), then apply Architecture Checklist below | | 2, "files", "workspace", "filesystem" | Read [files-universal-interface.md](./references/files-universal-interface.md) and [shared-workspace-architecture.md](./references/shared-workspace-architecture.md) | | 3, "tool", "mcp", "primitive", "crud" | Read [mcp-tool-design.md](./references/mcp-tool-design.md) | | 4, "domain tool", "when to add" | Read [from-primitives-to-domain-tools.md](./references/from-primitives-to-domain-tools.md) | | 5, "execution", "completion", "loop" | Read [agent-execution-patterns.md](./references/agent-execution-patterns.md) | | 6, "prompt", "system prompt", "behavior" | Read [system-prompt-design.md](./references/system-prompt-design.md) | | 7, "context", "inject", "runtime", "dynamic" | Read [dynamic-context-injection.md](./references/dynamic-context-injection.md) | | 8, "parity", "ui action", "capability map" | Read [action-parity-discipline.md](./references/action-parity-discipline.md) | | 9, "self-modify", "evolve", "git" | Read [self-modification.md](./references/self-modification.md) | | 10, "product", "progressive", "approval", "latent demand" | Read [product-implications.md](./references/product-implications.md) | | 11, "mobile", "ios", "android", "background", "checkpoint" | Read [mobile-patterns.md](./references/mobile-patterns.md) | | 11a, "icloud", "storage", "documents", "file state", "entitlement" | Read [mobile-storage.md](./references/mobile-storage.md) | | 11b, "background task", "battery", "on-device", "cloud routing" | Read [mobile-execution.md](./references/mobile-execution.md) | | 11c, "model tier", "token budget", "cost-aware", "batch", "caching" | Read [mobile-cost.md](./references/mobile-cost.md) | | 12, "test", "testing", "verify", "validate" | Read [agent-native-testing.md](./references/agent-native-testing.md) | | 13, "review", "refactor", "existing" | Read [refactoring-to-prompt-native.md](./references/refactoring-to-prompt-native.md) | | 14, "anti-pattern", "mistake", "wrong" | Read [anti-patterns.md](./references/anti-patterns.md) | | 15, "success", "criteria", "verify", "checklist" | Read [success-criteria.md](./references/success-criteria.md) | | 16, "hook", "hooks", "PreToolUse", "decision control", "async hook" | Read [hooks-patterns.md](./references/hooks-patterns.md) | | 0, "quick start", "getting started", "overview", "introduction" | Read [quick-start.md](./references/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, not `z.enum()` - [ ] **Eval Gate:** 10 Q/A pairs in CI (read-only, multi-hop, closed-data), 9/10 pass threshold. See [mcp-tool-design.md](./references/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_task` tool (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_context` tool) - [ ] **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](./references/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.**


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)