@lavralabs/lavra 0.7.0

package/plugins/lavra/skills/agent-native-architecture/references/from-primitives-to-domain-tools.md

@@ -0,0 +1,227 @@
+<overview>
+Start with pure primitives: bash, file operations, basic storage. This proves the architecture works and reveals what the agent actually needs. As patterns emerge, add domain-specific tools deliberately. This document covers when and how to evolve from primitives to domain tools, and when to graduate to optimized code.
+</overview>
+
+<start_with_primitives>
+## Start with Pure Primitives
+
+Begin every agent-native system with the most atomic tools possible:
+
+- `read_file` / `write_file` / `list_files`
+- `bash` (for everything else)
+- Basic storage (`store_item` / `get_item`)
+- HTTP requests (`fetch_url`)
+
+**Why start here:**
+
+1. **Proves the architecture** - If it works with primitives, your prompts are doing their job
+2. **Reveals actual needs** - You'll discover what domain concepts matter
+3. **Maximum flexibility** - Agent can do anything, not just what you anticipated
+4. **Forces good prompts** - You can't lean on tool logic as a crutch
+</start_with_primitives>
+
+<when_to_add_domain_tools>
+## When to Add Domain Tools
+
+As patterns emerge, you'll want to add domain-specific tools. This is good—but do it deliberately.
+
+### Vocabulary Anchoring
+
+**Add a domain tool when:** The agent needs to understand domain concepts.
+
+A `create_note` tool teaches the agent what "note" means in your system better than "write a file to the notes directory with this format."
+
+### Guardrails
+
+**Add a domain tool when:** Some operations need validation or constraints that shouldn't be left to agent judgment.
+
+```typescript
+// publish_to_feed might enforce format requirements or content policies
+tool("publish_to_feed", {
+  bookId: z.string(),
+  content: z.string(),
+  headline: z.string().max(100),  // Enforce headline length
+}, async ({ bookId, content, headline }) => {
+  // Validate content meets guidelines
+  if (containsProhibitedContent(content)) {
+    return { text: "Content doesn't meet guidelines", isError: true };
+  }
+  await feedService.publish({ bookId, content, headline, publishedAt: new Date() });
+});
+```
+
+### Efficiency
+
+**Add a domain tool when:** Common operations would take many primitive calls.
+
+```typescript
+// Primitive approach: multiple calls
+// Agent: read library.json, parse, find book, read full_text.txt, read introduction.md...
+
+// Domain tool: one call for common operation
+tool("get_book_with_content", { bookId: z.string() }, async ({ bookId }) => {
+  const book = await library.getBook(bookId);
+  const fullText = await readFile(`Research/${bookId}/full_text.txt`);
+  const intro = await readFile(`Research/${bookId}/introduction.md`);
+  return { text: JSON.stringify({ book, fullText, intro }) };
+});
+```
+</when_to_add_domain_tools>
+
+<the_rule>
+## The Rule for Domain Tools
+
+**Domain tools should represent one conceptual action from the user's perspective.**
+
+They can include mechanical validation, but **judgment about what to do or whether to do it belongs in the prompt**.
+
+### Wrong: Bundles Judgment
+
+```typescript
+// WRONG - analyze_and_publish bundles judgment into the tool
+tool("analyze_and_publish", async ({ input }) => {
+  const analysis = analyzeContent(input);      // Tool decides how to analyze
+  const shouldPublish = analysis.score > 0.7;  // Tool decides whether to publish
+  if (shouldPublish) {
+    await publish(analysis.summary);            // Tool decides what to publish
+  }
+});
+```
+
+### Right: One Action, Agent Decides
+
+```typescript
+// RIGHT - separate tools, agent decides
+tool("analyze_content", { content: z.string() }, ...);  // Returns analysis
+tool("publish", { content: z.string() }, ...);          // Publishes what agent provides
+
+// Prompt: "Analyze the content. If it's high quality, publish a summary."
+// Agent decides what "high quality" means and what summary to write.
+```
+
+### The Test
+
+Ask: "Who is making the decision here?"
+
+- If the answer is "the tool code" → you've encoded judgment, refactor
+- If the answer is "the agent based on the prompt" → good
+</the_rule>
+
+<keep_primitives_available>
+## Keep Primitives Available
+
+**Domain tools are shortcuts, not gates.**
+
+Unless there's a specific reason to restrict access (security, data integrity), the agent should still be able to use underlying primitives for edge cases.
+
+```typescript
+// Domain tool for common case
+tool("create_note", { title, content }, ...);
+
+// But primitives still available for edge cases
+tool("read_file", { path }, ...);
+tool("write_file", { path, content }, ...);
+
+// Agent can use create_note normally, but for weird edge case:
+// "Create a note in a non-standard location with custom metadata"
+// → Agent uses write_file directly
+```
+
+### When to Gate
+
+Gating (making domain tool the only way) is appropriate for:
+
+- **Security:** User authentication, payment processing
+- **Data integrity:** Operations that must maintain invariants
+- **Audit requirements:** Actions that must be logged in specific ways
+
+**The default is open.** When you do gate something, make it a conscious decision with a clear reason.
+</keep_primitives_available>
+
+<graduating_to_code>
+## Graduating to Code
+
+Some operations will need to move from agent-orchestrated to optimized code for performance or reliability.
+
+### The Progression
+
+```
+Stage 1: Agent uses primitives in a loop
+         → Flexible, proves the concept
+         → Slow, potentially expensive
+
+Stage 2: Add domain tools for common operations
+         → Faster, still agent-orchestrated
+         → Agent still decides when/whether to use
+
+Stage 3: For hot paths, implement in optimized code
+         → Fast, deterministic
+         → Agent can still trigger, but execution is code
+```
+
+### The Caveat
+
+**Even when an operation graduates to code, the agent should be able to:**
+
+1. Trigger the optimized operation itself
+2. Fall back to primitives for edge cases the optimized path doesn't handle
+
+Graduation is about efficiency. **Parity still holds.** The agent doesn't lose capability when you optimize.
+</graduating_to_code>
+
+<decision_framework>
+## Decision Framework
+
+### Should I Add a Domain Tool?
+
+| Question | If Yes |
+|----------|--------|
+| Is the agent confused about what this concept means? | Add for vocabulary anchoring |
+| Does this operation need validation the agent shouldn't decide? | Add with guardrails |
+| Is this a common multi-step operation? | Add for efficiency |
+| Would changing behavior require code changes? | Keep as prompt instead |
+
+### Should I Graduate to Code?
+
+| Question | If Yes |
+|----------|--------|
+| Is this operation called very frequently? | Consider graduating |
+| Does latency matter significantly? | Consider graduating |
+| Are token costs problematic? | Consider graduating |
+| Do you need deterministic behavior? | Graduate to code |
+| Does the operation need complex state management? | Graduate to code |
+
+### Should I Gate Access?
+
+| Question | If Yes |
+|----------|--------|
+| Is there a security requirement? | Gate appropriately |
+| Must this operation maintain data integrity? | Gate appropriately |
+| Is there an audit/compliance requirement? | Gate appropriately |
+| Is it just "safer" with no specific risk? | Keep primitives available |
+</decision_framework>
+
+<checklist>
+## Checklist: Primitives to Domain Tools
+
+### Starting Out
+- [ ] Begin with pure primitives (read, write, list, bash)
+- [ ] Write behavior in prompts, not tool logic
+- [ ] Let patterns emerge from actual usage
+
+### Adding Domain Tools
+- [ ] Clear reason: vocabulary anchoring, guardrails, or efficiency
+- [ ] Tool represents one conceptual action
+- [ ] Judgment stays in prompts, not tool code
+- [ ] Primitives remain available alongside domain tools
+
+### Graduating to Code
+- [ ] Hot path identified (frequent, latency-sensitive, or expensive)
+- [ ] Optimized version doesn't remove agent capability
+- [ ] Fallback to primitives for edge cases still works
+
+### Gating Decisions
+- [ ] Specific reason for each gate (security, integrity, audit)
+- [ ] Default is open access
+- [ ] Gates are conscious decisions, not defaults
+</checklist>

package/plugins/lavra/skills/agent-native-architecture/references/mcp-tool-design.md

@@ -0,0 +1,427 @@
+<overview>
+How to design MCP tools following prompt-native principles. Tools should be primitives that enable capability, not workflows that encode decisions.
+
+**Core principle:** Whatever a user can do, the agent should be able to do. Don't artificially limit the agent—give it the same primitives a power user would have.
+</overview>
+
+<principle name="primitives-not-workflows">
+## Tools Are Primitives, Not Workflows
+
+**Wrong approach:** Tools that encode business logic
+```typescript
+tool("process_feedback", {
+  feedback: z.string(),
+  category: z.enum(["bug", "feature", "question"]),
+  priority: z.enum(["low", "medium", "high"]),
+}, async ({ feedback, category, priority }) => {
+  // Tool decides how to process
+  const processed = categorize(feedback);
+  const stored = await saveToDatabase(processed);
+  const notification = await notify(priority);
+  return { processed, stored, notification };
+});
+```
+
+**Right approach:** Primitives that enable any workflow
+```typescript
+tool("store_item", {
+  key: z.string(),
+  value: z.any(),
+}, async ({ key, value }) => {
+  await db.set(key, value);
+  return { text: `Stored ${key}` };
+});
+
+tool("send_message", {
+  channel: z.string(),
+  content: z.string(),
+}, async ({ channel, content }) => {
+  await messenger.send(channel, content);
+  return { text: "Sent" };
+});
+```
+
+The agent decides categorization, priority, and when to notify based on the system prompt.
+</principle>
+
+<principle name="descriptive-names">
+## Tools Should Have Descriptive, Primitive Names
+
+Names should describe the capability, not the use case:
+
+| Wrong | Right |
+|-------|-------|
+| `process_user_feedback` | `store_item` |
+| `create_feedback_summary` | `write_file` |
+| `send_notification` | `send_message` |
+| `deploy_to_production` | `git_push` |
+
+The prompt tells the agent *when* to use primitives. The tool just provides *capability*.
+</principle>
+
+<principle name="simple-inputs">
+## Inputs Should Be Simple
+
+Tools accept data. They don't accept decisions.
+
+**Wrong:** Tool accepts decisions
+```typescript
+tool("format_content", {
+  content: z.string(),
+  format: z.enum(["markdown", "html", "json"]),
+  style: z.enum(["formal", "casual", "technical"]),
+}, ...)
+```
+
+**Right:** Tool accepts data, agent decides format
+```typescript
+tool("write_file", {
+  path: z.string(),
+  content: z.string(),
+}, ...)
+// Agent decides to write index.html with HTML content, or data.json with JSON
+```
+</principle>
+
+<principle name="rich-outputs">
+## Outputs Should Be Rich
+
+Return enough information for the agent to verify and iterate.
+
+**Wrong:** Minimal output
+```typescript
+async ({ key }) => {
+  await db.delete(key);
+  return { text: "Deleted" };
+}
+```
+
+**Right:** Rich output
+```typescript
+async ({ key }) => {
+  const existed = await db.has(key);
+  if (!existed) {
+    return { text: `Key ${key} did not exist` };
+  }
+  await db.delete(key);
+  return { text: `Deleted ${key}. ${await db.count()} items remaining.` };
+}
+```
+</principle>
+
+<design_template>
+## Tool Design Template
+
+```typescript
+import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+
+export const serverName = createSdkMcpServer({
+  name: "server-name",
+  version: "1.0.0",
+  tools: [
+    // READ operations
+    tool(
+      "read_item",
+      "Read an item by key",
+      { key: z.string().describe("Item key") },
+      async ({ key }) => {
+        const item = await storage.get(key);
+        return {
+          content: [{
+            type: "text",
+            text: item ? JSON.stringify(item, null, 2) : `Not found: ${key}`,
+          }],
+          isError: !item,
+        };
+      }
+    ),
+
+    tool(
+      "list_items",
+      "List all items, optionally filtered",
+      {
+        prefix: z.string().optional().describe("Filter by key prefix"),
+        limit: z.number().default(100).describe("Max items"),
+      },
+      async ({ prefix, limit }) => {
+        const items = await storage.list({ prefix, limit });
+        return {
+          content: [{
+            type: "text",
+            text: `Found ${items.length} items:\n${items.map(i => i.key).join("\n")}`,
+          }],
+        };
+      }
+    ),
+
+    // WRITE operations
+    tool(
+      "store_item",
+      "Store an item",
+      {
+        key: z.string().describe("Item key"),
+        value: z.any().describe("Item data"),
+      },
+      async ({ key, value }) => {
+        await storage.set(key, value);
+        return {
+          content: [{ type: "text", text: `Stored ${key}` }],
+        };
+      }
+    ),
+
+    tool(
+      "delete_item",
+      "Delete an item",
+      { key: z.string().describe("Item key") },
+      async ({ key }) => {
+        const existed = await storage.delete(key);
+        return {
+          content: [{
+            type: "text",
+            text: existed ? `Deleted ${key}` : `${key} did not exist`,
+          }],
+        };
+      }
+    ),
+
+    // EXTERNAL operations
+    tool(
+      "call_api",
+      "Make an HTTP request",
+      {
+        url: z.string().url(),
+        method: z.enum(["GET", "POST", "PUT", "DELETE"]).default("GET"),
+        body: z.any().optional(),
+      },
+      async ({ url, method, body }) => {
+        const response = await fetch(url, { method, body: JSON.stringify(body) });
+        const text = await response.text();
+        return {
+          content: [{
+            type: "text",
+            text: `${response.status} ${response.statusText}\n\n${text}`,
+          }],
+          isError: !response.ok,
+        };
+      }
+    ),
+  ],
+});
+```
+</design_template>
+
+<example name="feedback-server">
+## Example: Feedback Storage Server
+
+This server provides primitives for storing feedback. It does NOT decide how to categorize or organize feedback—that's the agent's job via the prompt.
+
+```typescript
+export const feedbackMcpServer = createSdkMcpServer({
+  name: "feedback",
+  version: "1.0.0",
+  tools: [
+    tool(
+      "store_feedback",
+      "Store a feedback item",
+      {
+        item: z.object({
+          id: z.string(),
+          author: z.string(),
+          content: z.string(),
+          importance: z.number().min(1).max(5),
+          timestamp: z.string(),
+          status: z.string().optional(),
+          urls: z.array(z.string()).optional(),
+          metadata: z.any().optional(),
+        }).describe("Feedback item"),
+      },
+      async ({ item }) => {
+        await db.feedback.insert(item);
+        return {
+          content: [{
+            type: "text",
+            text: `Stored feedback ${item.id} from ${item.author}`,
+          }],
+        };
+      }
+    ),
+
+    tool(
+      "list_feedback",
+      "List feedback items",
+      {
+        limit: z.number().default(50),
+        status: z.string().optional(),
+      },
+      async ({ limit, status }) => {
+        const items = await db.feedback.list({ limit, status });
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify(items, null, 2),
+          }],
+        };
+      }
+    ),
+
+    tool(
+      "update_feedback",
+      "Update a feedback item",
+      {
+        id: z.string(),
+        updates: z.object({
+          status: z.string().optional(),
+          importance: z.number().optional(),
+          metadata: z.any().optional(),
+        }),
+      },
+      async ({ id, updates }) => {
+        await db.feedback.update(id, updates);
+        return {
+          content: [{ type: "text", text: `Updated ${id}` }],
+        };
+      }
+    ),
+  ],
+});
+```
+
+The system prompt then tells the agent *how* to use these primitives:
+
+```markdown
+## Feedback Processing
+
+When someone shares feedback:
+1. Extract author, content, and any URLs
+2. Rate importance 1-5 based on actionability
+3. Store using feedback.store_feedback
+4. If high importance (4-5), notify the channel
+
+Use your judgment about importance ratings.
+```
+</example>
+
+<principle name="dynamic-capability-discovery">
+## Dynamic Capability Discovery vs Static Tool Mapping
+
+**This pattern is specifically for agent-native apps** where you want the agent to have full access to an external API—the same access a user would have. It follows the core agent-native principle: "Whatever the user can do, the agent can do."
+
+If you're building a constrained agent with limited capabilities, static tool mapping may be intentional. But for agent-native apps integrating with HealthKit, HomeKit, GraphQL, or similar APIs:
+
+**Static Tool Mapping (Anti-pattern for Agent-Native):**
+Build individual tools for each API capability. Always out of date, limits agent to only what you anticipated.
+
+**Dynamic Capability Discovery (Preferred):**
+Build a meta-tool that discovers what's available, and a generic tool that can access anything.
+
+```typescript
+// Dynamic: Agent discovers and uses any capability
+
+// Discovery tool - returns what's available at runtime
+tool("list_available_capabilities", async () => {
+  const quantityTypes = await healthKit.availableQuantityTypes();
+  const categoryTypes = await healthKit.availableCategoryTypes();
+
+  return {
+    text: `Available health metrics:\n` +
+          `Quantity types: ${quantityTypes.join(", ")}\n` +
+          `Category types: ${categoryTypes.join(", ")}\n` +
+          `\nUse read_health_data with any of these types.`
+  };
+});
+
+// Generic access tool - type is a string, API validates
+tool("read_health_data", {
+  dataType: z.string(),  // NOT z.enum - let HealthKit validate
+  startDate: z.string(),
+  endDate: z.string(),
+  aggregation: z.enum(["sum", "average", "samples"]).optional()
+}, async ({ dataType, startDate, endDate, aggregation }) => {
+  // HealthKit validates the type, returns helpful error if invalid
+  const result = await healthKit.query(dataType, startDate, endDate, aggregation);
+  return { text: JSON.stringify(result, null, 2) };
+});
+```
+
+**When to Use Each Approach:**
+
+| Dynamic (Agent-Native) | Static (Constrained Agent) |
+|------------------------|---------------------------|
+| Agent should access anything user can | Agent has intentionally limited scope |
+| External API with many endpoints (HealthKit, HomeKit, GraphQL) | Internal domain with fixed operations |
+| API evolves independently of your code | Tightly coupled domain logic |
+| You want full action parity | You want strict guardrails |
+
+**The agent-native default is Dynamic.** Only use Static when you're intentionally limiting the agent's capabilities.
+
+**Benefits:**
+- Agent can use any API capability, including ones added after your code shipped
+- API is the validator, not your enum definition
+- Smaller tool surface (2-3 tools vs N tools)
+- Agent naturally discovers capabilities by asking
+- Works with any API that has introspection (HealthKit, GraphQL, OpenAPI)
+</principle>
+
+<principle name="crud-completeness">
+## CRUD Completeness
+
+Every data type the agent can create, it should be able to read, update, and delete. Incomplete CRUD = broken action parity.
+
+**Anti-pattern: Create-only tools**
+```typescript
+// Can create but not modify or delete
+tool("create_experiment", { hypothesis, variable, metric })
+tool("write_journal_entry", { content, author, tags })
+// User: "Delete that experiment" → Agent: "I can't do that"
+```
+
+**Correct: Full CRUD for each entity**
+```typescript
+// Complete CRUD
+tool("create_experiment", { hypothesis, variable, metric })
+tool("read_experiment", { id })
+tool("update_experiment", { id, updates: { hypothesis?, status?, endDate? } })
+tool("delete_experiment", { id })
+
+tool("create_journal_entry", { content, author, tags })
+tool("read_journal", { query?, dateRange?, author? })
+tool("update_journal_entry", { id, content, tags? })
+tool("delete_journal_entry", { id })
+```
+
+**The CRUD Audit:**
+For each entity type in your app, verify:
+- [ ] Create: Agent can create new instances
+- [ ] Read: Agent can query/search/list instances
+- [ ] Update: Agent can modify existing instances
+- [ ] Delete: Agent can remove instances
+
+If any operation is missing, users will eventually ask for it and the agent will fail.
+</principle>
+
+<checklist>
+## MCP Tool Design Checklist
+
+**Fundamentals:**
+- [ ] Tool names describe capability, not use case
+- [ ] Inputs are data, not decisions
+- [ ] Outputs are rich (enough for agent to verify)
+- [ ] CRUD operations are separate tools (not one mega-tool)
+- [ ] No business logic in tool implementations
+- [ ] Error states clearly communicated via `isError`
+- [ ] Descriptions explain what the tool does, not when to use it
+
+**Dynamic Capability Discovery (for agent-native apps):**
+- [ ] For external APIs where agent should have full access, use dynamic discovery
+- [ ] Include a `list_*` or `discover_*` tool for each API surface
+- [ ] Use string inputs (not enums) when the API validates
+- [ ] Inject available capabilities into system prompt at runtime
+- [ ] Only use static tool mapping if intentionally limiting agent scope
+
+**CRUD Completeness:**
+- [ ] Every entity has create, read, update, delete operations
+- [ ] Every UI action has a corresponding agent tool
+- [ ] Test: "Can the agent undo what it just did?"
+</checklist>