claude-engineering-plugin/plugins/compound-engineering/skills/agent-native-architecture/references/files-universal-interface.md

Files are the universal interface for agent-native applications. Agents are naturally fluent with file operations—they already know how to read, write, and organize files. This document covers why files work so well, how to organize them, and the context.md pattern for accumulated knowledge.

<why_files>

Why Files

Agents are naturally good at files. Claude Code works because bash + filesystem is the most battle-tested agent interface. When building agent-native apps, lean into this.

Agents Already Know How

You don't need to teach the agent your API—it already knows cat, grep, mv, mkdir. File operations are the primitives it's most fluent with.

Files Are Inspectable

Users can see what the agent created, edit it, move it, delete it. No black box. Complete transparency into agent behavior.

Files Are Portable

Export is trivial. Backup is trivial. Users own their data. No vendor lock-in, no complex migration paths.

App State Stays in Sync

On mobile, if you use the file system with iCloud, all devices share the same file system. The agent's work on one device appears on all devices—without you having to build a server.

Directory Structure Is Information Architecture

The filesystem gives you hierarchy for free. /projects/acme/notes/ is self-documenting in a way that SELECT * FROM notes WHERE project_id = 123 isn't. </why_files>

<file_organization>

File Organization Patterns

Needs validation: These conventions are one approach that's worked so far, not a prescription. Better solutions should be considered.

A general principle of agent-native design: Design for what agents can reason about. The best proxy for that is what would make sense to a human. If a human can look at your file structure and understand what's going on, an agent probably can too.

Entity-Scoped Directories

Organize files around entities, not actors or file types:

{entity_type}/{entity_id}/
├── primary content
├── metadata
└── related materials

Example: Research/books/{bookId}/ contains everything about one book—full text, notes, sources, agent logs.

Naming Conventions

File Type	Naming Pattern	Example
Entity data	{entity}.json	library.json, status.json
Human-readable content	{content_type}.md	introduction.md, profile.md
Agent reasoning	agent_log.md	Per-entity agent history
Primary content	full_text.txt	Downloaded/extracted text
Multi-volume	volume{N}.txt	volume1.txt, volume2.txt
External sources	{source_name}.md	wikipedia.md, sparknotes.md
Checkpoints	{sessionId}.checkpoint	UUID-based
Configuration	config.json	Feature settings

Directory Naming

• Entity-scoped: {entityType}/{entityId}/ (e.g., Research/books/{bookId}/)
• Type-scoped: {type}/ (e.g., AgentCheckpoints/, AgentLogs/)
• Convention: Lowercase with underscores, not camelCase

Ephemeral vs. Durable Separation

Separate agent working files from user's permanent data:

Documents/
├── AgentCheckpoints/     # Ephemeral (can delete)
│   └── {sessionId}.checkpoint
├── AgentLogs/            # Ephemeral (debugging)
│   └── {type}/{sessionId}.md
└── Research/             # Durable (user's work)
    └── books/{bookId}/

The Split: Markdown vs JSON

• Markdown: For content users might read or edit
• JSON: For structured data the app queries </file_organization>

<context_md_pattern>

The context.md Pattern

A file the agent reads at the start of each session and updates as it learns:

# Context

## Who I Am
Reading assistant for the Every app.

## What I Know About This User
- Interested in military history and Russian literature
- Prefers concise analysis
- Currently reading War and Peace

## What Exists
- 12 notes in /notes
- 3 active projects
- User preferences at /preferences.md

## Recent Activity
- User created "Project kickoff" (2 hours ago)
- Analyzed passage about Austerlitz (yesterday)

## My Guidelines
- Don't spoil books they're reading
- Use their interests to personalize insights

## Current State
- No pending tasks
- Last sync: 10 minutes ago

Benefits

• Agent behavior evolves without code changes - Update the context, behavior changes
• Users can inspect and modify - Complete transparency
• Natural place for accumulated context - Learnings persist across sessions
• Portable across sessions - Restart agent, knowledge preserved

How It Works

1. Agent reads context.md at session start
2. Agent updates it when learning something important
3. System can also update it (recent activity, new resources)
4. Context persists across sessions

What to Include

Section	Purpose
Who I Am	Agent identity and role
What I Know About This User	Learned preferences, interests
What Exists	Available resources, data
Recent Activity	Context for continuity
My Guidelines	Learned rules and constraints
Current State	Session status, pending items
</context_md_pattern>

<files_vs_database>

Files vs. Database

Needs validation: This framing is informed by mobile development. For web apps, the tradeoffs are different.

Use files for...	Use database for...
Content users should read/edit	High-volume structured data
Configuration that benefits from version control	Data that needs complex queries
Agent-generated content	Ephemeral state (sessions, caches)
Anything that benefits from transparency	Data with relationships
Large text content	Data that needs indexing

The principle: Files for legibility, databases for structure. When in doubt, files—they're more transparent and users can always inspect them.

When Files Work Best

• Scale is small (one user's library, not millions of records)
• Transparency is valued over query speed
• Cloud sync (iCloud, Dropbox) works well with files

Hybrid Approach

Even if you need a database for performance, consider maintaining a file-based "source of truth" that the agent works with, synced to the database for the UI:

Files (agent workspace):
  Research/book_123/introduction.md

Database (UI queries):
  research_index: { bookId, path, title, createdAt }

</files_vs_database>

<conflict_model>

Conflict Model

If agents and users write to the same files, you need a conflict model.

Current Reality

Most implementations use last-write-wins via atomic writes:

try data.write(to: url, options: [.atomic])

This is simple but can lose changes.

Options

Strategy	Pros	Cons
Last write wins	Simple	Changes can be lost
Agent checks before writing	Preserves user edits	More complexity
Separate spaces	No conflicts	Less collaboration
Append-only logs	Never overwrites	Files grow forever
File locking	Safe concurrent access	Complexity, can block

Recommended Approaches

For files agents write frequently (logs, status): Last-write-wins is fine. Conflicts are rare.

For files users edit (profiles, notes): Consider explicit handling:

• Agent checks modification time before overwriting
• Or keep agent output separate from user-editable content
• Or use append-only pattern

iCloud Considerations

iCloud sync adds complexity. It creates {filename} (conflict).md files when sync conflicts occur. Monitor for these:

NotificationCenter.default.addObserver(
    forName: .NSMetadataQueryDidUpdate,
    ...
)

System Prompt Guidance

Tell the agent about the conflict model:

## Working with User Content

When you create content, the user may edit it afterward. Always read
existing files before modifying them—the user may have made improvements
you should preserve.

If a file has been modified since you last wrote it, ask before overwriting.

</conflict_model>

## Example: Reading App File Structure

Documents/
├── Library/
│   └── library.json              # Book metadata
├── Research/
│   └── books/
│       └── {bookId}/
│           ├── full_text.txt     # Downloaded content
│           ├── introduction.md   # Agent-generated, user-editable
│           ├── notes.md          # User notes
│           └── sources/
│               ├── wikipedia.md  # Research gathered by agent
│               └── reviews.md
├── Chats/
│   └── {conversationId}.json     # Chat history
├── Profile/
│   └── profile.md                # User reading profile
└── context.md                    # Agent's accumulated knowledge

How it works:

1. User adds book → creates entry in library.json
2. Agent downloads text → saves to Research/books/{id}/full_text.txt
3. Agent researches → saves to sources/
4. Agent generates intro → saves to introduction.md
5. User edits intro → agent sees changes on next read
6. Agent updates context.md with learnings

## Files as Universal Interface Checklist

Organization

• Entity-scoped directories ({type}/{id}/)
• Consistent naming conventions
• Ephemeral vs durable separation
• Markdown for human content, JSON for structured data

context.md

• Agent reads context at session start
• Agent updates context when learning
• Includes: identity, user knowledge, what exists, guidelines
• Persists across sessions

Conflict Handling

• Conflict model defined (last-write-wins, check-before-write, etc.)
• Agent guidance in system prompt
• iCloud conflict monitoring (if applicable)

Integration

• UI observes file changes (or shared service)
• Agent can read user edits
• User can inspect agent output