@lavralabs/lavra 0.7.0

package/plugins/lavra/opencode-src/plugin.ts

@@ -0,0 +1,176 @@
+/**
+ * lavra plugin for OpenCode
+ *
+ * Ports auto-recall.sh and memory-capture.sh hooks to OpenCode's event system.
+ * Subagent wrapup is handled separately via tool.execute.after with tool=task filter.
+ */
+
+import type { Plugin } from "@opencode-ai/plugin";
+import { resolve } from "node:path";
+
+console.log("[lavra] Plugin loaded successfully");
+
+export default {
+  // Set CLAUDE_PROJECT_DIR globally for all bd commands
+  "shell.env": async ({ directory }) => {
+    console.log("[lavra] shell.env hook triggered");
+
+    // Validate that directory is an absolute path (security)
+    if (!directory || !resolve(directory).startsWith("/")) {
+      return {};
+    }
+
+    return {
+      CLAUDE_PROJECT_DIR: directory,
+    };
+  },
+
+  // Auto-recall: inject relevant knowledge at session start
+  "session.created": async ({ directory }) => {
+    console.log("[lavra] session.created hook triggered");
+    // Validate absolute path (security)
+    if (!directory || !resolve(directory).startsWith("/")) {
+      return;
+    }
+
+    const hookScript = resolve(
+      import.meta.dir,
+      "../hooks/auto-recall.sh"
+    );
+
+    const proc = Bun.spawn(["bash", hookScript], {
+      env: {
+        ...process.env,
+        CLAUDE_PROJECT_DIR: directory,
+      },
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const stdout = await new Response(proc.stdout).text();
+    const stderr = await new Response(proc.stderr).text();
+
+    if (stderr) {
+      console.error("[lavra] auto-recall error:", stderr);
+    }
+
+    // Parse JSON output
+    try {
+      const output = JSON.parse(stdout);
+      if (output.hookSpecificOutput?.systemMessage) {
+        return {
+          systemMessage: output.hookSpecificOutput.systemMessage,
+        };
+      }
+    } catch (err) {
+      // Not JSON or parse error - no output to inject
+    }
+
+    return;
+  },
+
+  // Memory capture: extract knowledge from bd comments add commands
+  // Subagent wrapup: warn when subagents complete without logging knowledge
+  "tool.execute.after": async ({ tool, input, output, metadata, directory }) => {
+    // Handle subagent completion (tool=task)
+    if (tool === "task") {
+      // Check if BEAD_ID is referenced in the subagent output or title
+      const beadIdPattern = /\b(BD-[A-Za-z0-9._-]+|bdcompound-[A-Za-z0-9._-]+)\b/i;
+      const hasBeadId =
+        beadIdPattern.test(input?.title || "") ||
+        beadIdPattern.test(output || "") ||
+        beadIdPattern.test(metadata?.summary || "");
+
+      if (!hasBeadId) {
+        // No BEAD_ID found, no action needed
+        return;
+      }
+
+      // Check if subagent logged any knowledge comments
+      const hasKnowledgeComment =
+        (metadata?.summary || "").includes("bd comments add") ||
+        (metadata?.summary || "").includes("bd comment add");
+
+      if (hasKnowledgeComment) {
+        // Knowledge was captured, all good
+        return;
+      }
+
+      // BEAD_ID found but no knowledge logged - inject reminder
+      return {
+        systemMessage: `⚠️ **Subagent completed without logging knowledge**
+
+The subagent referenced a bead but didn't capture any learnings. Consider running:
+
+\`\`\`bash
+bd comments add <BEAD_ID> "LEARNED: <key insight from subagent work>"
+\`\`\`
+
+Use one of: LEARNED, DECISION, FACT, PATTERN, INVESTIGATION`,
+      };
+    }
+
+    // Pre-filter: only process bash commands (performance optimization)
+    if (tool !== "bash") {
+      return;
+    }
+
+    const command = input?.command;
+    if (!command || typeof command !== "string") {
+      return;
+    }
+
+    // Pre-filter: check for bd comments pattern before spawning subprocess
+    // This is a hot path - 95% of bash commands are not bd comments
+    if (!command.match(/bd\s+comments?\s+add\s+/)) {
+      return;
+    }
+
+    // Pre-filter: check for knowledge prefixes
+    if (!command.match(/(INVESTIGATION:|LEARNED:|DECISION:|FACT:|PATTERN:)/)) {
+      return;
+    }
+
+    // Validate directory path (security)
+    if (!directory || !resolve(directory).startsWith("/")) {
+      return;
+    }
+
+    // Construct stdin payload in Claude Code format
+    const stdinPayload = JSON.stringify({
+      tool_name: "Bash",
+      tool_input: {
+        command: command,
+      },
+      cwd: directory,
+    });
+
+    const hookScript = resolve(
+      import.meta.dir,
+      "../hooks/memory-capture.sh"
+    );
+
+    // Use Bun.spawn() with stdin piping (security: prevents shell injection)
+    const proc = Bun.spawn(["bash", hookScript], {
+      env: {
+        ...process.env,
+        CLAUDE_PROJECT_DIR: directory,
+      },
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    // Write stdin payload
+    const writer = proc.stdin.getWriter();
+    await writer.write(new TextEncoder().encode(stdinPayload));
+    await writer.close();
+
+    const stderr = await new Response(proc.stderr).text();
+    if (stderr) {
+      console.error("[lavra] memory-capture error:", stderr);
+    }
+
+    return;
+  },
+} satisfies Plugin;

package/plugins/lavra/scripts/import-plan.sh

@@ -0,0 +1,141 @@
+#!/bin/bash
+#
+# Import a markdown plan into beads
+#
+# Usage:
+#   ./import-plan.sh plan.md "Epic Title"
+#
+# Expected markdown format:
+#   # Epic Title
+#   Description here
+#
+#   ## Research / Background
+#   Research findings...
+#
+#   ## Implementation Steps
+#   ### Step 1: Database Schema
+#   Details...
+#
+#   ### Step 2: API Endpoints
+#   Details...
+#
+# This will create:
+#   - Epic bead with full plan as description
+#   - Child beads for each step (### headers under Implementation Steps)
+#   - Knowledge comments for research/background sections
+#
+
+set -euo pipefail
+
+PLAN_FILE="${1:-}"
+EPIC_TITLE="${2:-}"
+
+if [[ -z "$PLAN_FILE" || ! -f "$PLAN_FILE" ]]; then
+  echo "Usage: $0 <plan.md> <epic-title>"
+  echo ""
+  echo "Example:"
+  echo "  $0 auth-plan.md \"Add two-factor authentication\""
+  exit 1
+fi
+
+if [[ -z "$EPIC_TITLE" ]]; then
+  echo "Error: Epic title required"
+  echo "Usage: $0 <plan.md> <epic-title>"
+  exit 1
+fi
+
+echo "Importing plan from: $PLAN_FILE"
+echo "Epic title: $EPIC_TITLE"
+echo ""
+
+# Read full plan
+FULL_PLAN=$(cat "$PLAN_FILE")
+
+# Create epic bead
+echo "Creating epic bead..."
+EPIC_OUTPUT=$(bd create "$EPIC_TITLE" -d "$FULL_PLAN" --type epic 2>&1)
+EPIC_ID=$(echo "$EPIC_OUTPUT" | grep -oE '[A-Z]+-[0-9]+' | head -1)
+
+if [[ -z "$EPIC_ID" ]]; then
+  echo "Error: Failed to create epic bead"
+  echo "$EPIC_OUTPUT"
+  exit 1
+fi
+
+echo "Created epic: $EPIC_ID"
+echo ""
+
+# Extract research/background section and add as INVESTIGATION
+RESEARCH=$(awk '/^## (Research|Background|Context)/{flag=1;next}/^## /{flag=0}flag' "$PLAN_FILE")
+
+if [[ -n "$RESEARCH" ]]; then
+  echo "Adding research findings as INVESTIGATION..."
+  bd comments add "$EPIC_ID" "INVESTIGATION: Background and Research
+
+$RESEARCH"
+fi
+
+# Extract decisions section and add as DECISION
+DECISIONS=$(awk '/^## (Decisions|Choices|Approach)/{flag=1;next}/^## /{flag=0}flag' "$PLAN_FILE")
+
+if [[ -n "$DECISIONS" ]]; then
+  echo "Adding decisions..."
+  bd comments add "$EPIC_ID" "DECISION: Architectural Decisions
+
+$DECISIONS"
+fi
+
+# Extract implementation steps (### headers under Implementation/Tasks/Steps section)
+echo ""
+echo "Creating child beads for implementation steps..."
+
+PREV_BEAD=""
+STEP_NUM=0
+
+# Find the Implementation Steps section and extract ### headers
+awk '/^## (Implementation|Tasks|Steps|Work)/{flag=1;next}/^## /{flag=0}flag' "$PLAN_FILE" | \
+  grep -E '^### ' | \
+  while IFS= read -r line; do
+    ((STEP_NUM++))
+
+    # Extract step title (remove ###)
+    STEP_TITLE=$(echo "$line" | sed 's/^### *//')
+
+    # Extract step description (text between this ### and next ### or ##)
+    STEP_DESC=$(awk -v title="$line" '
+      $0 == title {flag=1; next}
+      /^##/ {flag=0}
+      flag && /^$/ {next}
+      flag {print}
+    ' "$PLAN_FILE" | head -20)
+
+    # Create child bead
+    if [[ -z "$PREV_BEAD" ]]; then
+      # First step, no dependencies
+      CHILD_OUTPUT=$(bd create "$STEP_TITLE" -d "$STEP_DESC" --parent "$EPIC_ID" 2>&1)
+    else
+      # Subsequent steps depend on previous
+      CHILD_OUTPUT=$(bd create "$STEP_TITLE" -d "$STEP_DESC" --parent "$EPIC_ID" --deps "$PREV_BEAD" 2>&1)
+    fi
+
+    CHILD_ID=$(echo "$CHILD_OUTPUT" | grep -oE '[A-Z]+-[0-9.]+' | head -1)
+
+    if [[ -n "$CHILD_ID" ]]; then
+      echo "  Created: $CHILD_ID - $STEP_TITLE"
+      PREV_BEAD="$CHILD_ID"
+    else
+      echo "  Warning: Failed to create bead for: $STEP_TITLE"
+    fi
+  done
+
+echo ""
+echo "Import complete!"
+echo ""
+echo "Epic: $EPIC_ID"
+echo "View: bd show $EPIC_ID"
+echo "List children: bd list --parent $EPIC_ID"
+echo ""
+echo "Next steps:"
+echo "  1. Review the created beads: bd show $EPIC_ID"
+echo "  2. Start work: /lavra-work ${EPIC_ID}.1"
+echo "  3. Or refine with research: /lavra-plan $EPIC_ID"

package/plugins/lavra/skills/agent-browser/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: agent-browser
+description: Browser automation using Vercel's agent-browser CLI. Use when you need to interact with web pages, fill forms, take screenshots, or scrape data. Alternative to Playwright MCP - uses Bash commands with ref-based element selection. Triggers on "browse website", "fill form", "click button", "take screenshot", "scrape page", "web automation".
+---
+
+# agent-browser: CLI Browser Automation
+
+Vercel's headless browser automation CLI designed for AI agents. Uses ref-based selection (@e1, @e2) from accessibility snapshots.
+
+## Setup Check
+
+```bash
+# Check installation
+command -v agent-browser >/dev/null 2>&1 && echo "Installed" || echo "NOT INSTALLED - run: npm install -g agent-browser && agent-browser install"
+```
+
+### Install if needed
+
+```bash
+npm install -g agent-browser
+agent-browser install  # Downloads Chromium
+```
+
+## Core Workflow
+
+**The snapshot + ref pattern is optimal for LLMs:**
+
+1. **Navigate** to URL
+2. **Snapshot** to get interactive elements with refs
+3. **Interact** using refs (@e1, @e2, etc.)
+4. **Re-snapshot** after navigation or DOM changes
+
+```bash
+# Step 1: Open URL
+agent-browser open https://example.com
+
+# Step 2: Get interactive elements with refs
+agent-browser snapshot -i --json
+
+# Step 3: Interact using refs
+agent-browser click @e1
+agent-browser fill @e2 "search query"
+
+# Step 4: Re-snapshot after changes
+agent-browser snapshot -i
+```
+
+## Key Commands
+
+### Navigation
+
+```bash
+agent-browser open <url>       # Navigate to URL
+agent-browser back             # Go back
+agent-browser forward          # Go forward
+agent-browser reload           # Reload page
+agent-browser close            # Close browser
+```
+
+### Snapshots (Essential for AI)
+
+```bash
+agent-browser snapshot              # Full accessibility tree
+agent-browser snapshot -i           # Interactive elements only (recommended)
+agent-browser snapshot -i --json    # JSON output for parsing
+agent-browser snapshot -c           # Compact (remove empty elements)
+agent-browser snapshot -d 3         # Limit depth
+```
+
+### Interactions
+
+```bash
+agent-browser click @e1                    # Click element
+agent-browser dblclick @e1                 # Double-click
+agent-browser fill @e1 "text"              # Clear and fill input
+agent-browser type @e1 "text"              # Type without clearing
+agent-browser press Enter                  # Press key
+agent-browser hover @e1                    # Hover element
+agent-browser check @e1                    # Check checkbox
+agent-browser uncheck @e1                  # Uncheck checkbox
+agent-browser select @e1 "option"          # Select dropdown option
+agent-browser scroll down 500              # Scroll (up/down/left/right)
+agent-browser scrollintoview @e1           # Scroll element into view
+```
+
+### Get Information
+
+```bash
+agent-browser get text @e1          # Get element text
+agent-browser get html @e1          # Get element HTML
+agent-browser get value @e1         # Get input value
+agent-browser get attr href @e1     # Get attribute
+agent-browser get title             # Get page title
+agent-browser get url               # Get current URL
+agent-browser get count "button"    # Count matching elements
+```
+
+### Screenshots & PDFs
+
+```bash
+agent-browser screenshot                      # Viewport screenshot
+agent-browser screenshot --full               # Full page
+agent-browser screenshot output.png           # Save to file
+agent-browser screenshot --full output.png    # Full page to file
+agent-browser pdf output.pdf                  # Save as PDF
+```
+
+### Wait
+
+```bash
+agent-browser wait @e1              # Wait for element
+agent-browser wait 2000             # Wait milliseconds
+agent-browser wait "text"           # Wait for text to appear
+```
+
+## Semantic Locators (Alternative to Refs)
+
+```bash
+agent-browser find role button click --name "Submit"
+agent-browser find text "Sign up" click
+agent-browser find label "Email" fill "user@example.com"
+agent-browser find placeholder "Search..." fill "query"
+```
+
+## Sessions (Parallel Browsers)
+
+```bash
+# Run multiple independent browser sessions
+agent-browser --session browser1 open https://site1.com
+agent-browser --session browser2 open https://site2.com
+
+# List active sessions
+agent-browser session list
+```
+
+## Examples
+
+### Login Flow
+
+```bash
+agent-browser open https://app.example.com/login
+agent-browser snapshot -i
+# Output shows: textbox "Email" [ref=e1], textbox "Password" [ref=e2], button "Sign in" [ref=e3]
+agent-browser fill @e1 "user@example.com"
+agent-browser fill @e2 "password123"
+agent-browser click @e3
+agent-browser wait 2000
+agent-browser snapshot -i  # Verify logged in
+```
+
+### Search and Extract
+
+```bash
+agent-browser open https://news.ycombinator.com
+agent-browser snapshot -i --json
+# Parse JSON to find story links
+agent-browser get text @e12  # Get headline text
+agent-browser click @e12     # Click to open story
+```
+
+### Form Filling
+
+```bash
+agent-browser open https://forms.example.com
+agent-browser snapshot -i
+agent-browser fill @e1 "John Doe"
+agent-browser fill @e2 "john@example.com"
+agent-browser select @e3 "United States"
+agent-browser check @e4  # Agree to terms
+agent-browser click @e5  # Submit button
+agent-browser screenshot confirmation.png
+```
+
+### Debug Mode
+
+```bash
+# Run with visible browser window
+agent-browser --headed open https://example.com
+agent-browser --headed snapshot -i
+agent-browser --headed click @e1
+```
+
+## JSON Output
+
+Add `--json` for structured output:
+
+```bash
+agent-browser snapshot -i --json
+```
+
+Returns:
+```json
+{
+  "success": true,
+  "data": {
+    "refs": {
+      "e1": {"name": "Submit", "role": "button"},
+      "e2": {"name": "Email", "role": "textbox"}
+    },
+    "snapshot": "- button \"Submit\" [ref=e1]\n- textbox \"Email\" [ref=e2]"
+  }
+}
+```
+
+## vs Playwright MCP
+
+| Feature | agent-browser (CLI) | Playwright MCP |
+|---------|---------------------|----------------|
+| Interface | Bash commands | MCP tools |
+| Selection | Refs (@e1) | Refs (e1) |
+| Output | Text/JSON | Tool responses |
+| Parallel | Sessions | Tabs |
+| Best for | Quick automation | Tool integration |
+
+Use agent-browser when:
+- You prefer Bash-based workflows
+- You want simpler CLI commands
+- You need quick one-off automation
+
+Use Playwright MCP when:
+- You need deep MCP tool integration
+- You want tool-based responses
+- You're building complex automation