@lavralabs/lavra 0.7.0

package/plugins/lavra/skills/agent-native-architecture/references/product-implications.md

@@ -0,0 +1,341 @@
+<overview>
+Agent-native architecture has consequences for how products feel, not just how they're built. This document covers progressive disclosure of complexity, discovering latent demand through agent usage, and designing approval flows that match stakes and reversibility.
+</overview>
+
+<progressive_disclosure>
+## Progressive Disclosure of Complexity
+
+The best agent-native applications are simple to start but endlessly powerful.
+
+### The Excel Analogy
+
+Excel is the canonical example: you can use it for a grocery list, or you can build complex financial models. The same tool, radically different depths of use.
+
+Claude Code has this quality: fix a typo, or refactor an entire codebase. The interface is the same—natural language—but the capability scales with the ask.
+
+### The Pattern
+
+Agent-native applications should aspire to this:
+
+**Simple entry:** Basic requests work immediately with no learning curve
+```
+User: "Organize my downloads"
+Agent: [Does it immediately, no configuration needed]
+```
+
+**Discoverable depth:** Users find they can do more as they explore
+```
+User: "Organize my downloads by project"
+Agent: [Adapts to preference]
+
+User: "Every Monday, review last week's downloads"
+Agent: [Sets up recurring workflow]
+```
+
+**No ceiling:** Power users can push the system in ways you didn't anticipate
+```
+User: "Cross-reference my downloads with my calendar and flag
+       anything I downloaded during a meeting that I haven't
+       followed up on"
+Agent: [Composes capabilities to accomplish this]
+```
+
+### How This Emerges
+
+This isn't something you design directly. It **emerges naturally from the architecture:**
+
+1. When features are prompts and tools are composable...
+2. Users can start simple ("organize my downloads")...
+3. And gradually discover complexity ("every Monday, review last week's...")...
+4. Without you having to build each level explicitly
+
+The agent meets users where they are.
+
+### Design Implications
+
+- **Don't force configuration upfront** - Let users start immediately
+- **Don't hide capabilities** - Make them discoverable through use
+- **Don't cap complexity** - If the agent can do it, let users ask for it
+- **Do provide hints** - Help users discover what's possible
+</progressive_disclosure>
+
+<latent_demand_discovery>
+## Latent Demand Discovery
+
+Traditional product development: imagine what users want, build it, see if you're right.
+
+Agent-native product development: build a capable foundation, observe what users ask the agent to do, formalize the patterns that emerge.
+
+### The Shift
+
+**Traditional approach:**
+```
+1. Imagine features users might want
+2. Build them
+3. Ship
+4. Hope you guessed right
+5. If wrong, rebuild
+```
+
+**Agent-native approach:**
+```
+1. Build capable foundation (atomic tools, parity)
+2. Ship
+3. Users ask agent for things
+4. Observe what they're asking for
+5. Patterns emerge
+6. Formalize patterns into domain tools or prompts
+7. Repeat
+```
+
+### The Flywheel
+
+```
+Build with atomic tools and parity
+           ↓
+Users ask for things you didn't anticipate
+           ↓
+Agent composes tools to accomplish them
+(or fails, revealing a capability gap)
+           ↓
+You observe patterns in what's being requested
+           ↓
+Add domain tools or prompts to optimize common patterns
+           ↓
+(Repeat)
+```
+
+### What You Learn
+
+**When users ask and the agent succeeds:**
+- This is a real need
+- Your architecture supports it
+- Consider optimizing with a domain tool if it's common
+
+**When users ask and the agent fails:**
+- This is a real need
+- You have a capability gap
+- Fix the gap: add tool, fix parity, improve context
+
+**When users don't ask for something:**
+- Maybe they don't need it
+- Or maybe they don't know it's possible (capability hiding)
+
+### Implementation
+
+**Log agent requests:**
+```typescript
+async function handleAgentRequest(request: string) {
+  // Log what users are asking for
+  await analytics.log({
+    type: 'agent_request',
+    request: request,
+    timestamp: Date.now(),
+  });
+
+  // Process request...
+}
+```
+
+**Track success/failure:**
+```typescript
+async function completeAgentSession(session: AgentSession) {
+  await analytics.log({
+    type: 'agent_session',
+    request: session.initialRequest,
+    succeeded: session.status === 'completed',
+    toolsUsed: session.toolCalls.map(t => t.name),
+    iterations: session.iterationCount,
+  });
+}
+```
+
+**Review patterns:**
+- What are users asking for most?
+- What's failing? Why?
+- What would benefit from a domain tool?
+- What needs better context injection?
+</latent_demand_discovery>
+
+<approval_and_agency>
+## Approval and User Agency
+
+When agents take unsolicited actions—doing things on their own rather than responding to explicit requests—you need to decide how much autonomy to grant.
+
+> **Note:** This framework applies to unsolicited agent actions. If the user explicitly asks the agent to do something ("send that email"), that's already approval—the agent just does it.
+
+### The Stakes/Reversibility Matrix
+
+Consider two dimensions:
+- **Stakes:** How much does it matter if this goes wrong?
+- **Reversibility:** How easy is it to undo?
+
+| Stakes | Reversibility | Pattern | Example |
+|--------|---------------|---------|---------|
+| Low | Easy | **Auto-apply** | Organizing files |
+| Low | Hard | **Quick confirm** | Publishing to a private feed |
+| High | Easy | **Suggest + apply** | Code changes with undo |
+| High | Hard | **Explicit approval** | Sending emails, payments |
+
+### Patterns in Detail
+
+**Auto-apply (low stakes, easy reversal):**
+```
+Agent: [Organizes files into folders]
+Agent: "I organized your downloads into folders by type.
+        You can undo with Cmd+Z or move them back."
+```
+User doesn't need to approve—it's easy to undo and doesn't matter much.
+
+**Quick confirm (low stakes, hard reversal):**
+```
+Agent: "I've drafted a post about your reading insights.
+        Publish to your feed?"
+        [Publish] [Edit first] [Cancel]
+```
+One-tap confirm because stakes are low, but it's hard to un-publish.
+
+**Suggest + apply (high stakes, easy reversal):**
+```
+Agent: "I recommend these code changes to fix the bug:
+        [Shows diff]
+        Apply? Changes can be reverted with git."
+        [Apply] [Modify] [Cancel]
+```
+Shows what will happen, makes reversal clear.
+
+**Explicit approval (high stakes, hard reversal):**
+```
+Agent: "I've drafted this email to your team about the deadline change:
+        [Shows full email]
+        This will send immediately and cannot be unsent.
+        Type 'send' to confirm."
+```
+Requires explicit action, makes consequences clear.
+
+### Self-Modification Considerations
+
+When agents can modify their own behavior—changing prompts, updating preferences, adjusting workflows—the goals are:
+
+1. **Visibility:** User can see what changed
+2. **Understanding:** User understands the effects
+3. **Rollback:** User can undo changes
+
+Approval flows are one way to achieve this. Audit logs with easy rollback could be another. **The principle is: make it legible.**
+</approval_and_agency>
+
+<capability_visibility>
+## Capability Visibility
+
+Users need to discover what the agent can do. Hidden capabilities lead to underutilization.
+
+### The Problem
+
+```
+User: "Help me with my reading"
+Agent: "What would you like help with?"
+// Agent doesn't mention it can publish to feed, research books,
+// generate introductions, analyze themes...
+```
+
+The agent can do these things, but the user doesn't know.
+
+### Solutions
+
+**Onboarding hints:**
+```
+Agent: "I can help you with your reading in several ways:
+        - Research any book (web search + save findings)
+        - Generate personalized introductions
+        - Publish insights to your reading feed
+        - Analyze themes across your library
+        What interests you?"
+```
+
+**Contextual suggestions:**
+```
+User: "I just finished reading 1984"
+Agent: "Great choice! Would you like me to:
+        - Research historical context?
+        - Compare it to other books in your library?
+        - Publish an insight about it to your feed?"
+```
+
+**Progressive revelation:**
+```
+// After user uses basic features
+Agent: "By the way, you can also ask me to set up
+        recurring tasks, like 'every Monday, review my
+        reading progress.' Just let me know!"
+```
+
+### Balance
+
+- **Don't overwhelm** with all capabilities upfront
+- **Do reveal** capabilities naturally through use
+- **Don't assume** users will discover things on their own
+- **Do make** capabilities visible when relevant
+</capability_visibility>
+
+<designing_for_trust>
+## Designing for Trust
+
+Agent-native apps require trust. Users are giving an AI significant capability. Build trust through:
+
+### Transparency
+
+- Show what the agent is doing (tool calls, progress)
+- Explain reasoning when it matters
+- Make all agent work inspectable (files, logs)
+
+### Predictability
+
+- Consistent behavior for similar requests
+- Clear patterns for when approval is needed
+- No surprises in what the agent can access
+
+### Reversibility
+
+- Easy undo for agent actions
+- Checkpoints before significant changes
+- Clear rollback paths
+
+### Control
+
+- User can stop agent at any time
+- User can adjust agent behavior (prompts, preferences)
+- User can restrict capabilities if desired
+</designing_for_trust>
+
+<checklist>
+## Product Design Checklist
+
+### Progressive Disclosure
+- [ ] Basic requests work immediately (no config)
+- [ ] Depth is discoverable through use
+- [ ] No artificial ceiling on complexity
+- [ ] Capability hints provided
+
+### Latent Demand Discovery
+- [ ] Agent requests are logged
+- [ ] Success/failure is tracked
+- [ ] Patterns are reviewed regularly
+- [ ] Common patterns formalized into tools/prompts
+
+### Approval & Agency
+- [ ] Stakes assessed for each action type
+- [ ] Reversibility assessed for each action type
+- [ ] Approval pattern matches stakes/reversibility
+- [ ] Self-modification is legible (visible, understandable, reversible)
+
+### Capability Visibility
+- [ ] Onboarding reveals key capabilities
+- [ ] Contextual suggestions provided
+- [ ] Users aren't expected to guess what's possible
+
+### Trust
+- [ ] Agent actions are transparent
+- [ ] Behavior is predictable
+- [ ] Actions are reversible
+- [ ] User has control
+</checklist>

package/plugins/lavra/skills/agent-native-architecture/references/refactoring-to-prompt-native.md

@@ -0,0 +1,317 @@
+<overview>
+How to refactor existing agent code to follow prompt-native principles. The goal: move behavior from code into prompts, and simplify tools into primitives.
+</overview>
+
+<diagnosis>
+## Diagnosing Non-Prompt-Native Code
+
+Signs your agent isn't prompt-native:
+
+**Tools that encode workflows:**
+```typescript
+// RED FLAG: Tool contains business logic
+tool("process_feedback", async ({ message }) => {
+  const category = categorize(message);        // Logic in code
+  const priority = calculatePriority(message); // Logic in code
+  await store(message, category, priority);    // Orchestration in code
+  if (priority > 3) await notify();            // Decision in code
+});
+```
+
+**Agent calls functions instead of figuring things out:**
+```typescript
+// RED FLAG: Agent is just a function caller
+"Use process_feedback to handle incoming messages"
+// vs.
+"When feedback comes in, decide importance, store it, notify if high"
+```
+
+**Artificial limits on agent capability:**
+```typescript
+// RED FLAG: Tool prevents agent from doing what users can do
+tool("read_file", async ({ path }) => {
+  if (!ALLOWED_PATHS.includes(path)) {
+    throw new Error("Not allowed to read this file");
+  }
+  return readFile(path);
+});
+```
+
+**Prompts that specify HOW instead of WHAT:**
+```markdown
+// RED FLAG: Micromanaging the agent
+When creating a summary:
+1. Use exactly 3 bullet points
+2. Each bullet must be under 20 words
+3. Format with em-dashes for sub-points
+4. Bold the first word of each bullet
+```
+</diagnosis>
+
+<refactoring_workflow>
+## Step-by-Step Refactoring
+
+**Step 1: Identify workflow tools**
+
+List all your tools. Mark any that:
+- Have business logic (categorize, calculate, decide)
+- Orchestrate multiple operations
+- Make decisions on behalf of the agent
+- Contain conditional logic (if/else based on content)
+
+**Step 2: Extract the primitives**
+
+For each workflow tool, identify the underlying primitives:
+
+| Workflow Tool | Hidden Primitives |
+|---------------|-------------------|
+| `process_feedback` | `store_item`, `send_message` |
+| `generate_report` | `read_file`, `write_file` |
+| `deploy_and_notify` | `git_push`, `send_message` |
+
+**Step 3: Move behavior to the prompt**
+
+Take the logic from your workflow tools and express it in natural language:
+
+```typescript
+// Before (in code):
+async function processFeedback(message) {
+  const priority = message.includes("crash") ? 5 :
+                   message.includes("bug") ? 4 : 3;
+  await store(message, priority);
+  if (priority >= 4) await notify();
+}
+```
+
+```markdown
+// After (in prompt):
+## Feedback Processing
+
+When someone shares feedback:
+1. Rate importance 1-5:
+   - 5: Crashes, data loss, security issues
+   - 4: Bug reports with clear reproduction steps
+   - 3: General suggestions, minor issues
+2. Store using store_item
+3. If importance >= 4, notify the team
+
+Use your judgment. Context matters more than keywords.
+```
+
+**Step 4: Simplify tools to primitives**
+
+```typescript
+// Before: 1 workflow tool
+tool("process_feedback", { message, category, priority }, ...complex logic...)
+
+// After: 2 primitive tools
+tool("store_item", { key: z.string(), value: z.any() }, ...simple storage...)
+tool("send_message", { channel: z.string(), content: z.string() }, ...simple send...)
+```
+
+**Step 5: Remove artificial limits**
+
+```typescript
+// Before: Limited capability
+tool("read_file", async ({ path }) => {
+  if (!isAllowed(path)) throw new Error("Forbidden");
+  return readFile(path);
+});
+
+// After: Full capability
+tool("read_file", async ({ path }) => {
+  return readFile(path);  // Agent can read anything
+});
+// Use approval gates for WRITES, not artificial limits on READS
+```
+
+**Step 6: Test with outcomes, not procedures**
+
+Instead of testing "does it call the right function?", test "does it achieve the outcome?"
+
+```typescript
+// Before: Testing procedure
+expect(mockProcessFeedback).toHaveBeenCalledWith(...)
+
+// After: Testing outcome
+// Send feedback → Check it was stored with reasonable importance
+// Send high-priority feedback → Check notification was sent
+```
+</refactoring_workflow>
+
+<before_after>
+## Before/After Examples
+
+**Example 1: Feedback Processing**
+
+Before:
+```typescript
+tool("handle_feedback", async ({ message, author }) => {
+  const category = detectCategory(message);
+  const priority = calculatePriority(message, category);
+  const feedbackId = await db.feedback.insert({
+    id: generateId(),
+    author,
+    message,
+    category,
+    priority,
+    timestamp: new Date().toISOString(),
+  });
+
+  if (priority >= 4) {
+    await discord.send(ALERT_CHANNEL, `High priority feedback from ${author}`);
+  }
+
+  return { feedbackId, category, priority };
+});
+```
+
+After:
+```typescript
+// Simple storage primitive
+tool("store_feedback", async ({ item }) => {
+  await db.feedback.insert(item);
+  return { text: `Stored feedback ${item.id}` };
+});
+
+// Simple message primitive
+tool("send_message", async ({ channel, content }) => {
+  await discord.send(channel, content);
+  return { text: "Sent" };
+});
+```
+
+System prompt:
+```markdown
+## Feedback Processing
+
+When someone shares feedback:
+1. Generate a unique ID
+2. Rate importance 1-5 based on impact and urgency
+3. Store using store_feedback with the full item
+4. If importance >= 4, send a notification to the team channel
+
+Importance guidelines:
+- 5: Critical (crashes, data loss, security)
+- 4: High (detailed bug reports, blocking issues)
+- 3: Medium (suggestions, minor bugs)
+- 2: Low (cosmetic, edge cases)
+- 1: Minimal (off-topic, duplicates)
+```
+
+**Example 2: Report Generation**
+
+Before:
+```typescript
+tool("generate_weekly_report", async ({ startDate, endDate, format }) => {
+  const data = await fetchMetrics(startDate, endDate);
+  const summary = summarizeMetrics(data);
+  const charts = generateCharts(data);
+
+  if (format === "html") {
+    return renderHtmlReport(summary, charts);
+  } else if (format === "markdown") {
+    return renderMarkdownReport(summary, charts);
+  } else {
+    return renderPdfReport(summary, charts);
+  }
+});
+```
+
+After:
+```typescript
+tool("query_metrics", async ({ start, end }) => {
+  const data = await db.metrics.query({ start, end });
+  return { text: JSON.stringify(data, null, 2) };
+});
+
+tool("write_file", async ({ path, content }) => {
+  writeFileSync(path, content);
+  return { text: `Wrote ${path}` };
+});
+```
+
+System prompt:
+```markdown
+## Report Generation
+
+When asked to generate a report:
+1. Query the relevant metrics using query_metrics
+2. Analyze the data and identify key trends
+3. Create a clear, well-formatted report
+4. Write it using write_file in the appropriate format
+
+Use your judgment about format and structure. Make it useful.
+```
+</before_after>
+
+<common_challenges>
+## Common Refactoring Challenges
+
+**"But the agent might make mistakes!"**
+
+Yes, and you can iterate. Change the prompt to add guidance:
+```markdown
+// Before
+Rate importance 1-5.
+
+// After (if agent keeps rating too high)
+Rate importance 1-5. Be conservative—most feedback is 2-3.
+Only use 4-5 for truly blocking or critical issues.
+```
+
+**"The workflow is complex!"**
+
+Complex workflows can still be expressed in prompts. The agent is smart.
+```markdown
+When processing video feedback:
+1. Check if it's a Loom, YouTube, or direct link
+2. For YouTube, pass URL directly to video analysis
+3. For others, download first, then analyze
+4. Extract timestamped issues
+5. Rate based on issue density and severity
+```
+
+**"We need deterministic behavior!"**
+
+Some operations should stay in code. That's fine. Prompt-native isn't all-or-nothing.
+
+Keep in code:
+- Security validation
+- Rate limiting
+- Audit logging
+- Exact format requirements
+
+Move to prompts:
+- Categorization decisions
+- Priority judgments
+- Content generation
+- Workflow orchestration
+
+**"What about testing?"**
+
+Test outcomes, not procedures:
+- "Given this input, does the agent achieve the right result?"
+- "Does stored feedback have reasonable importance ratings?"
+- "Are notifications sent for truly high-priority items?"
+</common_challenges>
+
+<checklist>
+## Refactoring Checklist
+
+Diagnosis:
+- [ ] Listed all tools with business logic
+- [ ] Identified artificial limits on agent capability
+- [ ] Found prompts that micromanage HOW
+
+Refactoring:
+- [ ] Extracted primitives from workflow tools
+- [ ] Moved business logic to system prompt
+- [ ] Removed artificial limits
+- [ ] Simplified tool inputs to data, not decisions
+
+Validation:
+- [ ] Agent achieves same outcomes with primitives
+- [ ] Behavior can be changed by editing prompts
+- [ ] New features could be added without new tools
+</checklist>