@soleur/opencode 0.0.0-stage → 3.354.2

package/skills/agent-native-architecture/references/dynamic-context-injection.md

@@ -0,0 +1,358 @@
+<overview>
+How to inject dynamic runtime context into agent system prompts. The agent needs to know what exists in the app to know what it can work with. Static prompts aren't enough—the agent needs to see the same context the user sees.
+
+**Core principle:** The user's context IS the agent's context.
+</overview>
+
+<why_context_matters>
+
+## Why Dynamic Context Injection?
+
+A static system prompt tells the agent what it CAN do. Dynamic context tells it what it can do RIGHT NOW with the user's actual data.
+
+**The failure case:**
+
+```
+User: "Write a little thing about Catherine the Great in my reading feed"
+Agent: "What system are you referring to? I'm not sure what reading feed means."
+```
+
+The agent failed because it didn't know:
+
+- What books exist in the user's library
+- What the "reading feed" is
+- What tools it has to publish there
+
+**The fix:** Inject runtime context about app state into the system prompt.
+</why_context_matters>
+
+<pattern name="context-injection">
+## The Context Injection Pattern
+
+Build your system prompt dynamically, including current app state:
+
+```swift
+func buildSystemPrompt() -> String {
+    // Gather current state
+    let availableBooks = libraryService.books
+    let recentActivity = analysisService.recentRecords(limit: 10)
+    let userProfile = profileService.currentProfile
+
+    return """
+    # Your Identity
+
+    You are a reading assistant for \(userProfile.name)'s library.
+
+    ## Available Books in User's Library
+
+    \(availableBooks.map { "- \"\($0.title)\" by \($0.author) (id: \($0.id))" }.joined(separator: "\n"))
+
+    ## Recent Reading Activity
+
+    \(recentActivity.map { "- Analyzed \"\($0.bookTitle)\": \($0.excerptPreview)" }.joined(separator: "\n"))
+
+    ## Your Capabilities
+
+    - **publish_to_feed**: Create insights that appear in the Feed tab
+    - **read_library**: View books, highlights, and analyses
+    - **web_search**: Search the internet for research
+    - **write_file**: Save research to Documents/Research/{bookId}/
+
+    When the user mentions "the feed" or "reading feed", they mean the Feed tab
+    where insights appear. Use `publish_to_feed` to create content there.
+    """
+}
+```
+
+</pattern>
+
+<what_to_inject>
+
+## What Context to Inject
+
+### 1. Available Resources
+
+What data/files exist that the agent can access?
+
+```swift
+## Available in User's Library
+
+Books:
+- "Moby Dick" by Herman Melville (id: book_123)
+- "1984" by George Orwell (id: book_456)
+
+Research folders:
+- Documents/Research/book_123/ (3 files)
+- Documents/Research/book_456/ (1 file)
+```
+
+### 2. Current State
+
+What has the user done recently? What's the current context?
+
+```swift
+## Recent Activity
+
+- 2 hours ago: Highlighted passage in "1984" about surveillance
+- Yesterday: Completed research on "Moby Dick" whale symbolism
+- This week: Added 3 new books to library
+```
+
+### 3. Capabilities Mapping
+
+What tool maps to what UI feature? Use the user's language.
+
+```swift
+## What You Can Do
+
+| User Says | You Should Use | Result |
+|-----------|----------------|--------|
+| "my feed" / "reading feed" | `publish_to_feed` | Creates insight in Feed tab |
+| "my library" / "my books" | `read_library` | Shows their book collection |
+| "research this" | `web_search` + `write_file` | Saves to Research folder |
+| "my profile" | `read_file("profile.md")` | Shows reading profile |
+```
+
+### 4. Domain Vocabulary
+
+Explain app-specific terms the user might use.
+
+```swift
+## Vocabulary
+
+- **Feed**: The Feed tab showing reading insights and analyses
+- **Research folder**: Documents/Research/{bookId}/ where research is stored
+- **Reading profile**: A markdown file describing user's reading preferences
+- **Highlight**: A passage the user marked in a book
+```
+
+</what_to_inject>
+
+<implementation_patterns>
+
+## Implementation Patterns
+
+### Pattern 1: Service-Based Injection (Swift/iOS)
+
+```swift
+class AgentContextBuilder {
+    let libraryService: BookLibraryService
+    let profileService: ReadingProfileService
+    let activityService: ActivityService
+
+    func buildContext() -> String {
+        let books = libraryService.books
+        let profile = profileService.currentProfile
+        let activity = activityService.recent(limit: 10)
+
+        return """
+        ## Library (\(books.count) books)
+        \(formatBooks(books))
+
+        ## Profile
+        \(profile.summary)
+
+        ## Recent Activity
+        \(formatActivity(activity))
+        """
+    }
+
+    private func formatBooks(_ books: [Book]) -> String {
+        books.map { "- \"\($0.title)\" (id: \($0.id))" }.joined(separator: "\n")
+    }
+}
+
+// Usage in agent initialization
+let context = AgentContextBuilder(
+    libraryService: .shared,
+    profileService: .shared,
+    activityService: .shared
+).buildContext()
+
+let systemPrompt = basePrompt + "\n\n" + context
+```
+
+### Pattern 2: Hook-Based Injection (TypeScript)
+
+```typescript
+interface ContextProvider {
+  getContext(): Promise<string>;
+}
+
+class LibraryContextProvider implements ContextProvider {
+  async getContext(): Promise<string> {
+    const books = await db.books.list();
+    const recent = await db.activity.recent(10);
+
+    return `
+## Library
+${books.map(b => `- "${b.title}" (${b.id})`).join('\n')}
+
+## Recent
+${recent.map(r => `- ${r.description}`).join('\n')}
+    `.trim();
+  }
+}
+
+// Compose multiple providers
+async function buildSystemPrompt(providers: ContextProvider[]): Promise<string> {
+  const contexts = await Promise.all(providers.map(p => p.getContext()));
+  return [BASE_PROMPT, ...contexts].join('\n\n');
+}
+```
+
+### Pattern 3: Template-Based Injection
+
+```markdown
+# System Prompt Template (system-prompt.template.md)
+
+You are a reading assistant.
+
+## Available Books
+
+{{#each books}}
+- "{{title}}" by {{author}} (id: {{id}})
+{{/each}}
+
+## Capabilities
+
+{{#each capabilities}}
+- **{{name}}**: {{description}}
+{{/each}}
+
+## Recent Activity
+
+{{#each recentActivity}}
+- {{timestamp}}: {{description}}
+{{/each}}
+```
+
+```typescript
+// Render at runtime
+const prompt = Handlebars.compile(template)({
+  books: await libraryService.getBooks(),
+  capabilities: getCapabilities(),
+  recentActivity: await activityService.getRecent(10),
+});
+```
+
+</implementation_patterns>
+
+<context_freshness>
+
+## Context Freshness
+
+Context should be injected at agent initialization, and optionally refreshed during long sessions.
+
+**At initialization:**
+
+```swift
+// Always inject fresh context when starting an agent
+func startChatAgent() async -> AgentSession {
+    let context = await buildCurrentContext()  // Fresh context
+    return await AgentOrchestrator.shared.startAgent(
+        config: ChatAgent.config,
+        systemPrompt: basePrompt + context
+    )
+}
+```
+
+**During long sessions (optional):**
+
+```swift
+// For long-running agents, provide a refresh tool
+tool("refresh_context", "Get current app state") { _ in
+    let books = libraryService.books
+    let recent = activityService.recent(10)
+    return """
+    Current library: \(books.count) books
+    Recent: \(recent.map { $0.summary }.joined(separator: ", "))
+    """
+}
+```
+
+**What NOT to do:**
+
+```swift
+// DON'T: Use stale context from app launch
+let cachedContext = appLaunchContext  // Stale!
+// Books may have been added, activity may have changed
+```
+
+</context_freshness>
+
+<examples>
+## Real-World Example: Every Reader
+
+The Every Reader app injects context for its chat agent:
+
+```swift
+func getChatAgentSystemPrompt() -> String {
+    // Get current library state
+    let books = BookLibraryService.shared.books
+    let analyses = BookLibraryService.shared.analysisRecords.prefix(10)
+    let profile = ReadingProfileService.shared.getProfileForSystemPrompt()
+
+    let bookList = books.map { book in
+        "- \"\(book.title)\" by \(book.author) (id: \(book.id))"
+    }.joined(separator: "\n")
+
+    let recentList = analyses.map { record in
+        let title = books.first { $0.id == record.bookId }?.title ?? "Unknown"
+        return "- From \"\(title)\": \"\(record.excerptPreview)\""
+    }.joined(separator: "\n")
+
+    return """
+    # Reading Assistant
+
+    You help the user with their reading and book research.
+
+    ## Available Books in User's Library
+
+    \(bookList.isEmpty ? "No books yet." : bookList)
+
+    ## Recent Reading Journal (Latest Analyses)
+
+    \(recentList.isEmpty ? "No analyses yet." : recentList)
+
+    ## Reading Profile
+
+    \(profile)
+
+    ## Your Capabilities
+
+    - **Publish to Feed**: Create insights using `publish_to_feed` that appear in the Feed tab
+    - **Library Access**: View books and highlights using `read_library`
+    - **Research**: Search web and save to Documents/Research/{bookId}/
+    - **Profile**: Read/update the user's reading profile
+
+    When the user asks you to "write something for their feed" or "add to my reading feed",
+    use the `publish_to_feed` tool with the relevant book_id.
+    """
+}
+```
+
+**Result:** When user says "write a little thing about Catherine the Great in my reading feed", the agent:
+
+1. Sees "reading feed" → knows to use `publish_to_feed`
+2. Sees available books → finds the relevant book ID
+3. Creates appropriate content for the Feed tab
+</examples>
+
+<checklist>
+## Context Injection Checklist
+
+Before launching an agent:
+
+- [ ] System prompt includes current resources (books, files, data)
+- [ ] Recent activity is visible to the agent
+- [ ] Capabilities are mapped to user vocabulary
+- [ ] Domain-specific terms are explained
+- [ ] Context is fresh (gathered at agent start, not cached)
+
+When adding new features:
+
+- [ ] New resources are included in context injection
+- [ ] New capabilities are documented in system prompt
+- [ ] User vocabulary for the feature is mapped
+</checklist>

package/skills/agent-native-architecture/references/files-universal-interface.md

@@ -0,0 +1,314 @@
+<overview>
+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.
+</overview>
+
+<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:
+
+```markdown
+# 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:
+
+```swift
+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:
+
+```swift
+NotificationCenter.default.addObserver(
+    forName: .NSMetadataQueryDidUpdate,
+    ...
+)
+```
+
+### System Prompt Guidance
+
+Tell the agent about the conflict model:
+
+```markdown
+## 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>
+
+<examples>
+## 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
+</examples>
+
+<checklist>
+## 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
+</checklist>