@lavralabs/lavra 0.7.0

package/plugins/lavra/skills/agent-native-architecture/references/action-parity-discipline.md

@@ -0,0 +1,353 @@
+<overview>
+A structured discipline for ensuring agents can do everything users can do. Every UI action should have an equivalent agent tool. This isn't a one-time check—it's an ongoing practice integrated into your development workflow.
+
+**Core principle:** When adding a UI feature, add the corresponding tool in the same PR.
+</overview>
+
+<why_parity>
+## Why Action Parity Matters
+
+**The failure case:**
+```
+User: "Write something about Catherine the Great in my reading feed"
+Agent: "What system are you referring to? I'm not sure what reading feed means."
+```
+
+The user could publish to their feed through the UI. But the agent had no `publish_to_feed` tool. The fix was simple—add the tool. But the insight is profound:
+
+**Every action a user can take through the UI must have an equivalent tool the agent can call.**
+
+Without this parity:
+- Users ask agents to do things they can't do
+- Agents ask clarifying questions about features they should understand
+- The agent feels limited compared to direct app usage
+- Users lose trust in the agent's capabilities
+</why_parity>
+
+<capability_mapping>
+## The Capability Map
+
+Maintain a structured map of UI actions to agent tools:
+
+| UI Action | UI Location | Agent Tool | System Prompt Reference |
+|-----------|-------------|------------|-------------------------|
+| View library | Library tab | `read_library` | "View books and highlights" |
+| Add book | Library → Add | `add_book` | "Add books to library" |
+| Publish insight | Analysis view | `publish_to_feed` | "Create insights for Feed tab" |
+| Start research | Book detail | `start_research` | "Research books via web search" |
+| Edit profile | Settings | `write_file(profile.md)` | "Update reading profile" |
+| Take screenshot | Camera | N/A (user action) | -- |
+| Search web | Chat | `web_search` | "Search the internet" |
+
+**Update this table whenever adding features.**
+
+### Template for Your App
+
+```markdown
+# Capability Map - [Your App Name]
+
+| UI Action | UI Location | Agent Tool | System Prompt | Status |
+|-----------|-------------|------------|---------------|--------|
+| | | | | Missing |
+| | | | | Done |
+| | | | | N/A |
+```
+
+Status meanings:
+- Done: Tool exists and is documented in system prompt
+- Missing: UI action exists but no agent equivalent
+- N/A: User-only action (e.g., biometric auth, camera capture)
+</capability_mapping>
+
+<parity_workflow>
+## The Action Parity Workflow
+
+### When Adding a New Feature
+
+Before merging any PR that adds UI functionality:
+
+```
+1. What action is this?
+   → "User can publish an insight to their reading feed"
+
+2. Does an agent tool exist for this?
+   → Check tool definitions
+   → If NO: Create the tool
+
+3. Is it documented in the system prompt?
+   → Check system prompt capabilities section
+   → If NO: Add documentation
+
+4. Is the context available?
+   → Does agent know what "feed" means?
+   → Does agent see available books?
+   → If NO: Add to context injection
+
+5. Update the capability map
+   → Add row to tracking document
+```
+
+### PR Checklist
+
+Add to your PR template:
+
+```markdown
+## Agent-Native Checklist
+
+- [ ] Every new UI action has a corresponding agent tool
+- [ ] System prompt updated to mention new capability
+- [ ] Agent has access to same data UI uses
+- [ ] Capability map updated
+- [ ] Tested with natural language request
+```
+</parity_workflow>
+
+<parity_audit>
+## The Parity Audit
+
+Periodically audit your app for action parity gaps:
+
+### Step 1: List All UI Actions
+
+Walk through every screen and list what users can do:
+
+```
+Library Screen:
+- View list of books
+- Search books
+- Filter by category
+- Add new book
+- Delete book
+- Open book detail
+
+Book Detail Screen:
+- View book info
+- Start research
+- View highlights
+- Add highlight
+- Share book
+- Remove from library
+
+Feed Screen:
+- View insights
+- Create new insight
+- Edit insight
+- Delete insight
+- Share insight
+
+Settings:
+- Edit profile
+- Change theme
+- Export data
+- Delete account
+```
+
+### Step 2: Check Tool Coverage
+
+For each action, verify:
+
+```
+View list of books      → read_library
+Search books            → read_library (with query param)
+Filter by category      → MISSING (add filter param to read_library)
+Add new book            → MISSING (need add_book tool)
+Delete book             → delete_book
+Open book detail        → read_library (single book)
+
+Start research          → start_research
+View highlights         → read_library (includes highlights)
+Add highlight           → MISSING (need add_highlight tool)
+Share book              → MISSING (or N/A if sharing is UI-only)
+
+View insights           → read_library (includes feed)
+Create new insight      → publish_to_feed
+Edit insight            → MISSING (need update_feed_item tool)
+Delete insight          → MISSING (need delete_feed_item tool)
+```
+
+### Step 3: Prioritize Gaps
+
+Not all gaps are equal:
+
+**High priority (users will ask for this):**
+- Add new book
+- Create/edit/delete content
+- Core workflow actions
+
+**Medium priority (occasional requests):**
+- Filter/search variations
+- Export functionality
+- Sharing features
+
+**Low priority (rarely requested via agent):**
+- Theme changes
+- Account deletion
+- Settings that are UI-preference
+</parity_audit>
+
+<tool_design_for_parity>
+## Designing Tools for Parity
+
+### Match Tool Granularity to UI Granularity
+
+If the UI has separate buttons for "Edit" and "Delete", consider separate tools:
+
+```typescript
+// Matches UI granularity
+tool("update_feed_item", { id, content, headline }, ...);
+tool("delete_feed_item", { id }, ...);
+
+// vs. combined (harder for agent to discover)
+tool("modify_feed_item", { id, action: "update" | "delete", ... }, ...);
+```
+
+### Use User Vocabulary in Tool Names
+
+```typescript
+// Good: Matches what users say
+tool("publish_to_feed", ...);  // "publish to my feed"
+tool("add_book", ...);         // "add this book"
+tool("start_research", ...);   // "research this"
+
+// Bad: Technical jargon
+tool("create_analysis_record", ...);
+tool("insert_library_item", ...);
+tool("initiate_web_scrape_workflow", ...);
+```
+
+### Return What the UI Shows
+
+If the UI shows a confirmation with details, the tool should too:
+
+```typescript
+// UI shows: "Added 'Moby Dick' to your library"
+// Tool should return the same:
+tool("add_book", async ({ title, author }) => {
+  const book = await library.add({ title, author });
+  return {
+    text: `Added "${book.title}" by ${book.author} to your library (id: ${book.id})`
+  };
+});
+```
+</tool_design_for_parity>
+
+<context_parity>
+## Context Parity
+
+Whatever the user sees, the agent should be able to access.
+
+### The Problem
+
+```swift
+// UI shows recent analyses in a list
+ForEach(analysisRecords) { record in
+    AnalysisRow(record: record)
+}
+
+// But system prompt only mentions books, not analyses
+let systemPrompt = """
+## Available Books
+\(books.map { $0.title })
+// Missing: recent analyses!
+"""
+```
+
+The user sees their reading journal. The agent doesn't. This creates a disconnect.
+
+### The Fix
+
+```swift
+// System prompt includes what UI shows
+let systemPrompt = """
+## Available Books
+\(books.map { "- \($0.title)" }.joined(separator: "\n"))
+
+## Recent Reading Journal
+\(analysisRecords.prefix(10).map { "- \($0.summary)" }.joined(separator: "\n"))
+"""
+```
+
+### Context Parity Checklist
+
+For each screen in your app:
+- [ ] What data does this screen display?
+- [ ] Is that data available to the agent?
+- [ ] Can the agent access the same level of detail?
+</context_parity>
+
+<continuous_parity>
+## Maintaining Parity Over Time
+
+### Git Hooks / CI Checks
+
+```bash
+#!/bin/bash
+# pre-commit hook: check for new UI actions without tools
+
+# Find new SwiftUI Button/onTapGesture additions
+NEW_ACTIONS=$(git diff --cached --name-only | xargs grep -l "Button\|onTapGesture")
+
+if [ -n "$NEW_ACTIONS" ]; then
+    echo "New UI actions detected. Did you add corresponding agent tools?"
+    echo "Files: $NEW_ACTIONS"
+    echo ""
+    echo "Checklist:"
+    echo "  [ ] Agent tool exists for new action"
+    echo "  [ ] System prompt documents new capability"
+    echo "  [ ] Capability map updated"
+fi
+```
+
+### Automated Parity Testing
+
+```typescript
+// parity.test.ts
+describe('Action Parity', () => {
+  const capabilityMap = loadCapabilityMap();
+
+  for (const [action, toolName] of Object.entries(capabilityMap)) {
+    if (toolName === 'N/A') continue;
+
+    test(`${action} has agent tool: ${toolName}`, () => {
+      expect(agentTools.map(t => t.name)).toContain(toolName);
+    });
+
+    test(`${toolName} is documented in system prompt`, () => {
+      expect(systemPrompt).toContain(toolName);
+    });
+  }
+});
+```
+
+### Regular Audits
+
+Schedule periodic reviews:
+
+```markdown
+## Monthly Parity Audit
+
+1. Review all PRs merged this month
+2. Check each for new UI actions
+3. Verify tool coverage
+4. Update capability map
+5. Test with natural language requests
+```
+</continuous_parity>
+
+<checklist>
+## Action Parity Checklist
+
+For every PR with UI changes:
+- [ ] Listed all new UI actions
+- [ ] Verified agent tool exists for each action
+- [ ] Updated system prompt with new capabilities
+- [ ] Added to capability map
+- [ ] Tested with natural language request
+
+For periodic audits:
+- [ ] Walked through every screen
+- [ ] Listed all possible user actions
+- [ ] Checked tool coverage for each
+- [ ] Prioritized gaps by likelihood of user request
+- [ ] Created issues for high-priority gaps
+</checklist>

package/plugins/lavra/skills/agent-native-architecture/references/agent-execution-patterns.md

@@ -0,0 +1,362 @@
+<overview>
+Agent execution patterns for building robust agent loops. This covers how agents signal completion, track partial progress for resume, select appropriate model tiers, and handle context limits.
+</overview>
+
+<completion_signals>
+## Completion Signals
+
+Agents need an explicit way to say "I'm done."
+
+### Anti-Pattern: Heuristic Detection
+
+Detecting completion through heuristics is fragile:
+
+- Consecutive iterations without tool calls
+- Checking for expected output files
+- Tracking "no progress" states
+- Time-based timeouts
+
+These break in edge cases and create unpredictable behavior.
+
+### Pattern: Explicit Completion Tool
+
+Provide a `complete_task` tool that:
+- Takes a summary of what was accomplished
+- Returns a signal that stops the loop
+- Works identically across all agent types
+
+```typescript
+tool("complete_task", {
+  summary: z.string().describe("Summary of what was accomplished"),
+  status: z.enum(["success", "partial", "blocked"]).optional(),
+}, async ({ summary, status = "success" }) => {
+  return {
+    text: summary,
+    shouldContinue: false,  // Key: signals loop should stop
+  };
+});
+```
+
+### The ToolResult Pattern
+
+Structure tool results to separate success from continuation:
+
+```swift
+struct ToolResult {
+    let success: Bool           // Did tool succeed?
+    let output: String          // What happened?
+    let shouldContinue: Bool    // Should agent loop continue?
+}
+
+extension ToolResult {
+    static func success(_ output: String) -> ToolResult {
+        // Tool succeeded, keep going
+        ToolResult(success: true, output: output, shouldContinue: true)
+    }
+
+    static func error(_ message: String) -> ToolResult {
+        // Tool failed but recoverable, agent can try something else
+        ToolResult(success: false, output: message, shouldContinue: true)
+    }
+
+    static func complete(_ summary: String) -> ToolResult {
+        // Task done, stop the loop
+        ToolResult(success: true, output: summary, shouldContinue: false)
+    }
+}
+```
+
+### Key Insight
+
+**This is different from success/failure:**
+
+- A tool can **succeed** AND signal **stop** (task complete)
+- A tool can **fail** AND signal **continue** (recoverable error, try something else)
+
+### System Prompt Guidance
+
+Tell the agent when to complete:
+
+```markdown
+## Completing Tasks
+
+When you've accomplished the user's request:
+1. Verify your work (read back files you created, check results)
+2. Call `complete_task` with a summary of what you did
+3. Don't keep working after the goal is achieved
+
+If you're blocked and can't proceed:
+- Call `complete_task` with status "blocked" and explain why
+- Don't loop forever trying the same thing
+```
+</completion_signals>
+
+<partial_completion>
+## Partial Completion
+
+For multi-step tasks, track progress at the task level for resume capability.
+
+### Task State Tracking
+
+```swift
+enum TaskStatus {
+    case pending      // Not yet started
+    case inProgress   // Currently working on
+    case completed    // Finished successfully
+    case failed       // Couldn't complete (with reason)
+    case skipped      // Intentionally not done
+}
+
+struct AgentTask {
+    let id: String
+    let description: String
+    var status: TaskStatus
+    var notes: String?  // Why it failed, what was done
+}
+
+struct AgentSession {
+    var tasks: [AgentTask]
+
+    var isComplete: Bool {
+        tasks.allSatisfy { $0.status == .completed || $0.status == .skipped }
+    }
+
+    var progress: (completed: Int, total: Int) {
+        let done = tasks.filter { $0.status == .completed }.count
+        return (done, tasks.count)
+    }
+}
+```
+
+### Partial Completion Scenarios
+
+**Agent hits max iterations before finishing:**
+- Some tasks completed, some pending
+- Checkpoint saved with current state
+- Resume continues from where it left off, not from beginning
+
+**Agent fails on one task:**
+- Task marked `.failed` with error in notes
+- Other tasks may continue (agent decides)
+- Orchestrator doesn't automatically abort entire session
+
+**Network error mid-task:**
+- Current iteration throws
+- Session marked `.failed`
+- Checkpoint preserves messages up to that point
+- Resume possible from checkpoint
+
+### Checkpoint Structure
+
+```swift
+struct AgentCheckpoint: Codable {
+    let sessionId: String
+    let agentType: String
+    let messages: [Message]          // Full conversation history
+    let iterationCount: Int
+    let tasks: [AgentTask]           // Task state
+    let customState: [String: Any]   // Agent-specific state
+    let timestamp: Date
+
+    var isValid: Bool {
+        // Checkpoints expire (default 1 hour)
+        Date().timeIntervalSince(timestamp) < 3600
+    }
+}
+```
+
+### Resume Flow
+
+1. On app launch, scan for valid checkpoints
+2. Show user: "You have an incomplete session. Resume?"
+3. On resume:
+   - Restore messages to conversation
+   - Restore task states
+   - Continue agent loop from where it left off
+4. On dismiss:
+   - Delete checkpoint
+   - Start fresh if user tries again
+</partial_completion>
+
+<model_tier_selection>
+## Model Tier Selection
+
+Different agents need different intelligence levels. Use the cheapest model that achieves the outcome.
+
+### Tier Guidelines
+
+| Agent Type | Recommended Tier | Reasoning |
+|------------|-----------------|-----------|
+| Chat/Conversation | Balanced (Sonnet) | Fast responses, good reasoning |
+| Research | Balanced (Sonnet) | Tool loops, not ultra-complex synthesis |
+| Content Generation | Balanced (Sonnet) | Creative but not synthesis-heavy |
+| Complex Analysis | Powerful (Opus) | Multi-document synthesis, nuanced judgment |
+| Profile Generation | Powerful (Opus) | Photo analysis, complex pattern recognition |
+| Quick Queries | Fast (Haiku) | Simple lookups, quick transformations |
+| Simple Classification | Fast (Haiku) | High volume, simple decisions |
+
+### Cost Optimization Strategies
+
+1. **Start with balanced, upgrade if quality insufficient**
+2. **Use fast tier for tool-heavy loops** where each turn is simple
+3. **Reserve powerful tier for synthesis tasks** (comparing multiple sources)
+4. **Consider token limits per turn** to control costs
+5. **Cache expensive operations** to avoid repeated calls
+</model_tier_selection>
+
+<context_limits>
+## Context Limits
+
+Agent sessions can extend indefinitely, but context windows don't. Design for bounded context from the start.
+
+### The Problem
+
+```
+Turn 1: User asks question → 500 tokens
+Turn 2: Agent reads file → 10,000 tokens
+Turn 3: Agent reads another file → 10,000 tokens
+Turn 4: Agent researches → 20,000 tokens
+...
+Turn 10: Context window exceeded
+```
+
+### Design Principles
+
+**1. Tools should support iterative refinement**
+
+Instead of all-or-nothing, design for summary → detail → full:
+
+```typescript
+tool("read_file", {
+  path: z.string(),
+  preview: z.boolean().default(true),  // Return first 1000 chars by default
+  full: z.boolean().default(false),    // Opt-in to full content
+}, ...);
+```
+
+**2. Provide consolidation tools**
+
+Give agents a way to consolidate learnings mid-session:
+
+```typescript
+tool("summarize_and_continue", {
+  keyPoints: z.array(z.string()),
+  nextSteps: z.array(z.string()),
+}, async ({ keyPoints, nextSteps }) => {
+  await saveSessionSummary({ keyPoints, nextSteps });
+  return { text: "Summary saved. Continuing with focus on: " + nextSteps.join(", ") };
+});
+```
+
+**3. Design for truncation**
+
+Assume the orchestrator may truncate early messages. Important context should be:
+- In the system prompt (always present)
+- In files (can be re-read)
+- Summarized in context.md
+
+### System Prompt Guidance
+
+```markdown
+## Managing Context
+
+For long tasks, periodically consolidate what you've learned:
+1. If you've gathered a lot of information, summarize key points
+2. Save important findings to files (they persist beyond context)
+3. Use `summarize_and_continue` if the conversation is getting long
+
+Don't try to hold everything in memory. Write it down.
+```
+</context_limits>
+
+<orchestrator_pattern>
+## Unified Agent Orchestrator
+
+One execution engine, many agent types. All agents use the same orchestrator with different configurations.
+
+```swift
+class AgentOrchestrator {
+    static let shared = AgentOrchestrator()
+
+    func run(config: AgentConfig, userMessage: String) async -> AgentResult {
+        var messages: [Message] = [
+            .system(config.systemPrompt),
+            .user(userMessage)
+        ]
+
+        var iteration = 0
+
+        while iteration < config.maxIterations {
+            let response = await claude.message(
+                model: config.modelTier.modelId,
+                messages: messages,
+                tools: config.tools
+            )
+
+            messages.append(.assistant(response))
+
+            for toolCall in response.toolCalls {
+                let result = await executeToolCall(toolCall, config: config)
+                messages.append(.toolResult(result))
+
+                if !result.shouldContinue {
+                    return AgentResult(
+                        status: .completed,
+                        output: result.output,
+                        iterations: iteration + 1
+                    )
+                }
+            }
+
+            if response.toolCalls.isEmpty {
+                break
+            }
+
+            iteration += 1
+        }
+
+        return AgentResult(
+            status: iteration >= config.maxIterations ? .maxIterations : .responded,
+            output: messages.last?.content ?? "",
+            iterations: iteration
+        )
+    }
+}
+```
+
+### Benefits
+
+- Consistent lifecycle management across all agent types
+- Automatic checkpoint/resume (critical for mobile)
+- Shared tool protocol
+- Easy to add new agent types
+- Centralized error handling and logging
+</orchestrator_pattern>
+
+<checklist>
+## Agent Execution Checklist
+
+### Completion Signals
+- [ ] `complete_task` tool provided (explicit completion)
+- [ ] No heuristic completion detection
+- [ ] Tool results include `shouldContinue` flag
+- [ ] System prompt guides when to complete
+
+### Partial Completion
+- [ ] Tasks tracked with status (pending, in_progress, completed, failed)
+- [ ] Checkpoints saved for resume
+- [ ] Progress visible to user
+- [ ] Resume continues from where left off
+
+### Model Tiers
+- [ ] Tier selected based on task complexity
+- [ ] Cost optimization considered
+- [ ] Fast tier for simple operations
+- [ ] Powerful tier reserved for synthesis
+
+### Context Limits
+- [ ] Tools support iterative refinement (preview vs full)
+- [ ] Consolidation mechanism available
+- [ ] Important context persisted to files
+- [ ] Truncation strategy defined
+</checklist>