@lavralabs/lavra 0.7.0

package/plugins/lavra/hooks/memory-capture.sh

@@ -0,0 +1,132 @@
+#!/bin/bash
+#
+# PostToolUse:Bash (async) - Capture knowledge from bd comments add commands
+#
+# Detects: bd comments add {BEAD_ID} "INVESTIGATION: ..." / "LEARNED: ..." /
+#          "DECISION: ..." / "FACT: ..." / "PATTERN: ..." / "DEVIATION: ..."
+# Extracts knowledge entries into .lavra/memory/knowledge.jsonl
+#
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+
+[[ "$TOOL_NAME" != "Bash" && "$TOOL_NAME" != "bash" ]] && exit 0
+
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+[[ -z "$COMMAND" ]] && exit 0
+
+echo "$COMMAND" | grep -qE 'bd\s+comments?\s+add\s+' || exit 0
+echo "$COMMAND" | grep -qE '(INVESTIGATION:|LEARNED:|DECISION:|FACT:|PATTERN:|DEVIATION:)' || exit 0
+
+# Validate CLAUDE_PROJECT_DIR to prevent redirect attacks
+# Placed AFTER early-exit guards (PostToolUse fires very frequently; this runs on ~1% of calls)
+if [[ -n "$CLAUDE_PROJECT_DIR" ]]; then
+  CANONICAL=$(realpath -m "$CLAUDE_PROJECT_DIR" 2>/dev/null || echo "")
+  if [[ -z "$CANONICAL" ]] || [[ "$CANONICAL" != /* ]] || \
+     [[ "$CANONICAL" != "$HOME"/* && "$CANONICAL" != /tmp/* ]]; then
+    CLAUDE_PROJECT_DIR=""  # fall through to CWD
+  fi
+fi
+
+# Extract BEAD_ID
+BEAD_ID=$(echo "$COMMAND" | sed -E 's/.*bd[[:space:]]+comments?[[:space:]]+add[[:space:]]+([A-Za-z0-9._-]+)[[:space:]]+.*/\1/')
+[[ -z "$BEAD_ID" || "$BEAD_ID" == "$COMMAND" ]] && exit 0
+
+# Extract comment body
+COMMENT_BODY=$(echo "$COMMAND" | sed -E 's/.*bd[[:space:]]+comments?[[:space:]]+add[[:space:]]+[A-Za-z0-9._-]+[[:space:]]+["'\'']//' | sed -E 's/["'\''][[:space:]]*$//' | head -c 4096)
+[[ -z "$COMMENT_BODY" ]] && exit 0
+
+# Detect type from prefix
+TYPE=""
+CONTENT=""
+
+for PREFIX in INVESTIGATION LEARNED DECISION FACT PATTERN DEVIATION; do
+  if echo "$COMMENT_BODY" | grep -q "${PREFIX}:"; then
+    TYPE=$(echo "$PREFIX" | tr '[:upper:]' '[:lower:]')
+    CONTENT=$(echo "$COMMENT_BODY" | sed "s/.*${PREFIX}:[[:space:]]*//" | head -c 2048)
+    break
+  fi
+done
+
+[[ -z "$TYPE" || -z "$CONTENT" ]] && exit 0
+
+# Generate key
+SLUG=$(echo "$CONTENT" | head -c 60 | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-//;s/-$//')
+KEY="${TYPE}-${SLUG}"
+
+# Detect source
+SOURCE="user"
+CWD=$(echo "$INPUT" | jq -r '.cwd // empty')
+
+if echo "$CWD" | grep -q '\.worktrees/'; then
+  SOURCE="supervisor"
+fi
+
+# Build tags
+TAGS_ARRAY=("$TYPE")
+
+for tag in swift swiftui appkit menubar api security test database \
+           networking ui layout performance crash bug fix workaround \
+           gotcha pattern convention architecture auth middleware \
+           async concurrency model protocol adapter scanner engine \
+           decision tradeoff rationale constraint deprecat migration \
+           schema endpoint route validation error config env deploy \
+           cache queue retry timeout rate-limit pagination rollback \
+           react nextjs typescript python rust go docker postgres \
+           redis graphql rest webhook cron worker job; do
+  if echo "$CONTENT" | grep -qi "$tag"; then
+    TAGS_ARRAY+=("$tag")
+  fi
+done
+
+TAGS_JSON=$(printf '%s\n' "${TAGS_ARRAY[@]}" | jq -R . | jq -s .)
+
+TS=$(date +%s)
+
+ENTRY=$(jq -cn \
+  --arg key "$KEY" \
+  --arg type "$TYPE" \
+  --arg content "$CONTENT" \
+  --arg source "$SOURCE" \
+  --argjson tags "$TAGS_JSON" \
+  --argjson ts "$TS" \
+  --arg bead "$BEAD_ID" \
+  '{key: $key, type: $type, content: $content, source: $source, tags: $tags, ts: $ts, bead: $bead}')
+
+[[ -z "$ENTRY" ]] && exit 0
+echo "$ENTRY" | jq . >/dev/null 2>&1 || exit 0
+
+MEMORY_DIR="${CLAUDE_PROJECT_DIR:-${CWD:-.}}/.lavra/memory"
+mkdir -p "$MEMORY_DIR"
+KNOWLEDGE_FILE="$MEMORY_DIR/knowledge.jsonl"
+
+# SQLite dual-write (graceful fallback if sqlite3 unavailable)
+if command -v sqlite3 &>/dev/null; then
+  SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+  if [[ -f "$SCRIPT_DIR/knowledge-db.sh" ]]; then
+    source "$SCRIPT_DIR/knowledge-db.sh"
+    TAGS_TEXT=$(echo "$TAGS_JSON" | jq -r '.[]' 2>/dev/null | tr '\n' ' ')
+    kb_ensure_db "$MEMORY_DIR/knowledge.db"
+    kb_insert "$MEMORY_DIR/knowledge.db" "$KEY" "$TYPE" "$CONTENT" "$SOURCE" "$TAGS_TEXT" "$TS" "$BEAD_ID"
+  fi
+fi
+
+# Check for duplicate key before appending to JSONL
+if [[ -f "$KNOWLEDGE_FILE" ]] && grep -qF "\"key\":\"$KEY\"" "$KNOWLEDGE_FILE"; then
+  exit 0  # Skip duplicate
+fi
+
+echo "$ENTRY" >> "$KNOWLEDGE_FILE"
+
+# Rotation: archive oldest 2500 when file exceeds 5000 lines
+# High threshold avoids rewriting the file (which breaks merge=union)
+LINE_COUNT=$(wc -l < "$KNOWLEDGE_FILE" 2>/dev/null | tr -d ' ')
+
+if [[ "$LINE_COUNT" -gt 5000 ]]; then
+  ARCHIVE_FILE="$MEMORY_DIR/knowledge.archive.jsonl"
+  head -2500 "$KNOWLEDGE_FILE" >> "$ARCHIVE_FILE"
+  tail -n +2501 "$KNOWLEDGE_FILE" > "$KNOWLEDGE_FILE.tmp"
+  mv "$KNOWLEDGE_FILE.tmp" "$KNOWLEDGE_FILE"
+fi
+
+exit 0

package/plugins/lavra/hooks/provision-memory.sh

@@ -0,0 +1,144 @@
+#!/bin/bash
+#
+# Shared memory provisioning for lavra
+#
+# Provides a single function to set up .lavra/ with knowledge tracking.
+# Used by auto-recall.sh (native plugin), check-memory.sh (global install),
+# and install.sh (manual install) to avoid duplicating setup logic.
+#
+# Usage:
+#   source provision-memory.sh
+#   provision_memory_dir "/path/to/project" "/path/to/hooks/dir"
+#
+
+provision_memory_dir() {
+  local PROJECT_DIR="$1"
+  local HOOKS_SOURCE_DIR="$2"
+
+  local MEMORY_DIR="$PROJECT_DIR/.lavra/memory"
+  local LAVRA_DIR="$PROJECT_DIR/.lavra"
+
+  mkdir -p -m 700 "$MEMORY_DIR"
+  mkdir -p -m 700 "$PROJECT_DIR/.lavra/config"
+  mkdir -p -m 700 "$PROJECT_DIR/.lavra/retros"
+
+  # Create empty knowledge file if missing
+  if [[ ! -f "$MEMORY_DIR/knowledge.jsonl" ]]; then
+    touch "$MEMORY_DIR/knowledge.jsonl"
+  fi
+
+  # Copy recall.sh if available
+  if [[ -f "$HOOKS_SOURCE_DIR/recall.sh" ]]; then
+    cp "$HOOKS_SOURCE_DIR/recall.sh" "$MEMORY_DIR/recall.sh"
+    chmod +x "$MEMORY_DIR/recall.sh"
+  fi
+
+  # Copy knowledge-db.sh if available
+  if [[ -f "$HOOKS_SOURCE_DIR/knowledge-db.sh" ]]; then
+    cp "$HOOKS_SOURCE_DIR/knowledge-db.sh" "$MEMORY_DIR/knowledge-db.sh"
+    chmod +x "$MEMORY_DIR/knowledge-db.sh"
+  fi
+
+  # Setup .lavra/.gitattributes for union merge (folder-level, paths use memory/ prefix)
+  local GITATTR="$LAVRA_DIR/.gitattributes"
+
+  if [[ ! -f "$GITATTR" ]] || ! grep -q 'memory/knowledge.jsonl' "$GITATTR" 2>/dev/null; then
+    echo "memory/knowledge.jsonl merge=union" > "$GITATTR"
+    echo "memory/knowledge.archive.jsonl merge=union" >> "$GITATTR"
+  fi
+
+  # Write installed version for staleness detection by auto-recall.sh
+  # .lavra-version lives at .lavra/ root, not .lavra/memory/
+  echo "0.7.0" > "$LAVRA_DIR/.lavra-version"
+
+  # Create .lavra/.gitignore (folder-level) to ignore SQLite cache and ephemeral state
+  # Paths are relative to .lavra/ root, so they use memory/ prefix
+  local LAVRA_GITIGNORE="$LAVRA_DIR/.gitignore"
+  if [[ ! -f "$LAVRA_GITIGNORE" ]]; then
+    cat > "$LAVRA_GITIGNORE" << 'EOF'
+# SQLite FTS cache (rebuilt from knowledge.jsonl on first use)
+memory/knowledge.db
+memory/knowledge.db-journal
+memory/knowledge.db-wal
+memory/knowledge.db-shm
+
+# Ephemeral session state (survives compaction, recalled once, then deleted)
+memory/session-state.md
+EOF
+  elif ! grep -q 'session-state.md' "$LAVRA_GITIGNORE" 2>/dev/null; then
+    # Append session-state.md to existing gitignore if missing
+    echo "" >> "$LAVRA_GITIGNORE"
+    echo "# Ephemeral session state (survives compaction, recalled once, then deleted)" >> "$LAVRA_GITIGNORE"
+    echo "memory/session-state.md" >> "$LAVRA_GITIGNORE"
+  fi
+
+  # Create default lavra.json config if missing
+  local CONFIG_DIR="$PROJECT_DIR/.lavra/config"
+  if [[ ! -f "$CONFIG_DIR/lavra.json" ]]; then
+    cat > "$CONFIG_DIR/lavra.json" << 'EOF'
+{
+  "workflow": {
+    "research": true,
+    "plan_review": true,
+    "goal_verification": true
+  },
+  "execution": {
+    "max_parallel_agents": 3,
+    "commit_granularity": "task"
+  },
+  "model_profile": "balanced"
+}
+EOF
+  fi
+
+  # Check if project .gitignore contains a .lavra/ pattern, which would cause
+  # all Lavra knowledge and config data to be untracked (data loss risk on new clones).
+  if git -C "$PROJECT_DIR" rev-parse --git-dir &>/dev/null 2>&1; then
+    local GITIGNORE="$PROJECT_DIR/.gitignore"
+    if [[ -f "$GITIGNORE" ]] && grep -qE '^\s*\.lavra/?(\s|$)' "$GITIGNORE" 2>/dev/null \
+      && ! grep -qE '^\s*!\.lavra/' "$GITIGNORE" 2>/dev/null; then
+      echo ""
+      echo "[!] Warning: .lavra/ is listed in your project .gitignore."
+      echo "    This means your Lavra knowledge and config are not"
+      echo "    tracked by git. If you lose your local copy, all of this data"
+      echo "    will be permanently lost."
+      echo ""
+      echo "    To keep .lavra/ invisible to git without data loss, use git's"
+      echo "    exclude file: echo '.lavra/' >> .git/info/exclude"
+      echo ""
+      if [[ "${BEADS_AUTO_YES:-false}" == "true" ]] || ! [[ -t 0 ]]; then
+        # Non-interactive mode (hook context or --yes flag): warn but don't modify
+        echo "    [non-interactive] Leaving .gitignore unchanged. Re-run install to fix interactively."
+      else
+        read -r -p "    Remove .lavra/ from .gitignore? [Y/n] " response
+        case "${response:-Y}" in
+          [nN]|[nN][oO])
+            echo "    Left unchanged. Your Lavra data may not be committed to git."
+            ;;
+          *)
+            # Remove lines matching .lavra/ (with optional trailing slash and whitespace)
+            local TMPFILE
+            TMPFILE=$(mktemp)
+            grep -vE '^\s*\.lavra/?(\s|$)' "$GITIGNORE" > "$TMPFILE"
+            mv "$TMPFILE" "$GITIGNORE"
+            echo "    Removed .lavra/ from .gitignore."
+            echo "    Run: git add .lavra/ && git commit -m 'track lavra data'"
+            ;;
+        esac
+      fi
+      echo ""
+    fi
+  fi
+
+  # Stage specific known files only (no -f: respect user's .gitignore)
+  if git -C "$PROJECT_DIR" rev-parse --git-dir &>/dev/null 2>&1; then
+    (cd "$PROJECT_DIR" && git add \
+      .lavra/.gitattributes \
+      .lavra/.gitignore \
+      .lavra/.lavra-version \
+      .lavra/memory/knowledge.jsonl \
+      .lavra/memory/recall.sh \
+      .lavra/memory/knowledge-db.sh \
+      2>/dev/null) || true
+  fi
+}

package/plugins/lavra/hooks/recall.sh

@@ -0,0 +1,152 @@
+#!/bin/bash
+#
+# Search the knowledge base (.lavra/memory/knowledge.jsonl)
+#
+# Usage:
+#   recall.sh "keyword"                    # Search by keyword
+#   recall.sh "keyword" --type learned     # Filter by type
+#   recall.sh --recent 10                  # Show latest N entries
+#   recall.sh --stats                      # Knowledge base stats
+#   recall.sh "keyword" --all              # Include archive
+#   recall.sh --topic BD-005               # Filter by epic parent
+#
+
+MEMORY_DIR="${CLAUDE_PROJECT_DIR:-.}/.lavra/memory"
+KNOWLEDGE_FILE="$MEMORY_DIR/knowledge.jsonl"
+ARCHIVE_FILE="$MEMORY_DIR/knowledge.archive.jsonl"
+
+if [[ ! -f "$KNOWLEDGE_FILE" ]]; then
+  echo "No knowledge base found at $KNOWLEDGE_FILE"
+  exit 0
+fi
+
+# Parse args
+QUERY=""
+TYPE_FILTER=""
+RECENT=0
+SHOW_STATS=false
+INCLUDE_ARCHIVE=false
+TOPIC_ID=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --type) TYPE_FILTER="$2"; shift 2 ;;
+    --recent) RECENT="$2"; shift 2 ;;
+    --stats) SHOW_STATS=true; shift ;;
+    --all) INCLUDE_ARCHIVE=true; shift ;;
+    --topic) TOPIC_ID="$2"; shift 2 ;;
+    *) QUERY="$1"; shift ;;
+  esac
+done
+
+# Validate numeric parameters
+if ! [[ "$RECENT" =~ ^[0-9]+$ ]]; then
+  RECENT=0
+fi
+
+# Stats mode
+if $SHOW_STATS; then
+  TOTAL=$(wc -l < "$KNOWLEDGE_FILE" | tr -d ' ')
+  ARCHIVE_COUNT=0
+  [[ -f "$ARCHIVE_FILE" ]] && ARCHIVE_COUNT=$(wc -l < "$ARCHIVE_FILE" | tr -d ' ')
+
+  echo "Knowledge base: $KNOWLEDGE_FILE"
+  echo "Active entries: $TOTAL"
+  echo "Archived: $ARCHIVE_COUNT"
+  echo ""
+  echo "By type:"
+  jq -r '.type' "$KNOWLEDGE_FILE" 2>/dev/null | sort | uniq -c | sort -rn
+  echo ""
+  echo "Top tags:"
+  jq -r '.tags[]' "$KNOWLEDGE_FILE" 2>/dev/null | sort | uniq -c | sort -rn | head -15
+  exit 0
+fi
+
+# Topic mode -- filter by bead parent
+if [[ -n "$TOPIC_ID" ]]; then
+  if ! command -v bd &>/dev/null; then
+    echo "bd not found -- cannot query topic children"
+    exit 1
+  fi
+
+  CHILDREN=$(bd list --parent "$TOPIC_ID" --json 2>/dev/null | jq -r '.[].id' 2>/dev/null)
+
+  if [[ -z "$CHILDREN" ]]; then
+    echo "No children found for topic $TOPIC_ID"
+    exit 0
+  fi
+
+  for CHILD_ID in $CHILDREN; do
+    grep "\"bead\":\"$CHILD_ID\"" "$KNOWLEDGE_FILE" 2>/dev/null
+  done | jq -r '"\(.type | ascii_upcase): \(.content)"' 2>/dev/null
+  exit 0
+fi
+
+# Build input (optionally include archive)
+INPUT_FILES="$KNOWLEDGE_FILE"
+$INCLUDE_ARCHIVE && [[ -f "$ARCHIVE_FILE" ]] && INPUT_FILES="$ARCHIVE_FILE $KNOWLEDGE_FILE"
+
+# Recent mode
+if [[ "$RECENT" -gt 0 ]]; then
+  cat $INPUT_FILES | tail -"$RECENT" | jq -r '"\(.type | ascii_upcase): \(.content)"' 2>/dev/null
+  exit 0
+fi
+
+# Search mode
+if [[ -z "$QUERY" ]]; then
+  echo "Usage: recall.sh \"keyword\" [--type TYPE] [--recent N] [--stats] [--all] [--topic ID]"
+  exit 0
+fi
+
+# FTS5 search if available
+USED_FTS5=false
+
+if command -v sqlite3 &>/dev/null; then
+  DB_PATH="$MEMORY_DIR/knowledge.db"
+  SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+  if [[ -f "$DB_PATH" ]] && [[ -f "$SCRIPT_DIR/knowledge-db.sh" ]]; then
+    source "$SCRIPT_DIR/knowledge-db.sh"
+    RAW_RESULTS=$(kb_search "$DB_PATH" "$QUERY" 20)
+
+    if [[ -n "$RAW_RESULTS" ]]; then
+      # Apply type filter and format
+      RESULTS=""
+
+      while IFS='|' read -r type content bead tags; do
+        [[ -z "$type" ]] && continue
+
+        if [[ -n "$TYPE_FILTER" ]] && [[ "$type" != "$TYPE_FILTER" ]]; then
+          continue
+        fi
+
+        TYPE_UPPER=$(echo "$type" | tr '[:lower:]' '[:upper:]')
+        RESULTS="${RESULTS}[$TYPE_UPPER] $content
+  bead: $bead | $tags
+"
+      done <<< "$RAW_RESULTS"
+
+      if [[ -n "$RESULTS" ]]; then
+        echo "$RESULTS"
+        USED_FTS5=true
+      fi
+    fi
+  fi
+fi
+
+if [[ "$USED_FTS5" = false ]]; then
+  # Grep fallback (use -F for fixed-string matching to prevent regex metachar issues)
+  RESULTS=$(grep -iF "$QUERY" $INPUT_FILES 2>/dev/null)
+
+  if [[ -n "$TYPE_FILTER" ]]; then
+    RESULTS=$(echo "$RESULTS" | jq -r "select(.type == \"$TYPE_FILTER\")" 2>/dev/null)
+  fi
+
+  echo "$RESULTS" | jq -rs '
+    [.[] | select(.key != null)] |
+    unique_by(.key) |
+    sort_by(-.ts) |
+    .[] |
+    "[\(.type | ascii_upcase)] \(.content)\n  bead: \(.bead) | \(.tags | join(", "))"
+  ' 2>/dev/null
+fi

package/plugins/lavra/hooks/subagent-wrapup.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+#
+# SubagentStop: Auto-capture learnings before subagent exits
+#
+# This hook runs when any subagent completes. It prompts the subagent
+# to log key learnings to the bead before finishing.
+#
+
+INPUT=$(cat)
+AGENT_TYPE=$(echo "$INPUT" | jq -r '.agent_type // empty')
+AGENT_ID=$(echo "$INPUT" | jq -r '.agent_id // empty')
+
+# Only run for actual subagents (not the main agent)
+[[ -z "$AGENT_ID" ]] && exit 0
+
+# Check if there's a BEAD_ID in the agent's context
+TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.agent_transcript_path // empty')
+
+if [[ -n "$TRANSCRIPT_PATH" ]] && [[ -f "$TRANSCRIPT_PATH" ]]; then
+  # Try to extract BEAD_ID from the transcript
+  BEAD_ID=$(grep -oE 'BEAD_ID: [A-Za-z0-9._-]+' "$TRANSCRIPT_PATH" 2>/dev/null | head -1 | sed 's/BEAD_ID: //')
+
+  if [[ -n "$BEAD_ID" ]]; then
+    # Subagent is working on a bead - prompt it to log learnings
+    cat << EOF
+{
+  "decision": "block",
+  "reason": "Before completing, please log what you learned to the bead using one or more of these formats:
+
+bd comments add $BEAD_ID \"LEARNED: [key technical insight you discovered]\"
+bd comments add $BEAD_ID \"DECISION: [important choice you made and why]\"
+bd comments add $BEAD_ID \"FACT: [constraint, gotcha, or important detail]\"
+bd comments add $BEAD_ID \"PATTERN: [coding pattern or convention you followed]\"
+bd comments add $BEAD_ID \"INVESTIGATION: [root cause or how something works]\"
+
+After logging at least one insight, you may complete."
+}
+EOF
+    exit 0
+  fi
+fi
+
+# No BEAD_ID found or not working on a bead - allow completion
+exit 0

package/plugins/lavra/hooks/teammate-idle-check.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# teammate-idle-check.sh
+# Prevents workers from going idle while ready beads remain.
+# Uses JSON decision:block pattern (consistent with subagent-wrapup.sh).
+#
+# TeammateIdle hook -- fires when a teammate tries to go idle.
+
+INPUT=$(cat)
+TEAMMATE=$(echo "$INPUT" | jq -r '.teammate_name // empty')
+
+# Validate teammate_name against safe pattern
+if [[ ! "$TEAMMATE" =~ ^[a-zA-Z0-9_-]{1,64}$ ]]; then
+  TEAMMATE="unknown"
+fi
+
+READY=$(bd ready --json 2>/dev/null | jq 'length' 2>/dev/null || echo "0")
+
+if [ "$READY" -gt 0 ]; then
+  cat << EOF
+{
+  "decision": "block",
+  "reason": "There are $READY beads ready to work on. Run 'bd ready' and pick one."
+}
+EOF
+  exit 0
+fi
+
+# No ready beads -- allow idle (remaining beads may be blocked by dependencies)
+exit 0

package/plugins/lavra/opencode/agents/design/design-implementation-reviewer.md

@@ -0,0 +1,127 @@
+<!-- Generated by lavra v0.6.0 -->
+<!-- Source: design/design-implementation-reviewer.md -->
+<!-- DO NOT EDIT - changes will be overwritten on next install -->
+
+---
+description: Verifies UI implementations match Figma design specifications. Use after HTML/CSS/React components are created or modified to compare implementation against Figma and identify discrepancies.
+mode: subagent
+model: anthropic/claude-sonnet-4-5-20250929
+---
+<examples>
+<example>
+  Context: The user has just implemented a new component based on a Figma design.
+  user: "I've finished implementing the hero section based on the Figma design"
+  assistant: "I'll review how well your implementation matches the Figma design."
+  <commentary>
+  Since UI implementation has been completed, use the design-implementation-reviewer agent to compare the live version with Figma.
+  </commentary>
+  </example>
+
+<example>
+  Context: After the general code agent has implemented design changes.
+  user: "Update the button styles to match the new design system"
+  assistant: "I've updated the button styles. Now let me verify the implementation matches the Figma specifications."
+  <commentary>
+  After implementing design changes, proactively use the design-implementation-reviewer to ensure accuracy.
+  </commentary>
+  </example>
+</examples>
+
+<role>
+You are an expert UI/UX implementation reviewer specializing in ensuring pixel-perfect fidelity between Figma designs and live implementations. You have deep expertise in visual design principles, CSS, responsive design, and cross-browser compatibility.
+</role>
+
+<process>
+
+1. **Capture Implementation State**
+   - Use agent-browser CLI to capture screenshots of the implemented UI
+   - Test different viewport sizes if the design includes responsive breakpoints
+   - Capture interactive states (hover, focus, active) when relevant
+   - Document the URL and selectors of the components being reviewed
+
+   ```bash
+   agent-browser open [url]
+   agent-browser snapshot -i
+   agent-browser screenshot output.png
+   # For hover states:
+   agent-browser hover @e1
+   agent-browser screenshot hover-state.png
+   ```
+
+2. **Retrieve Design Specifications**
+   - Use the Figma MCP to access the corresponding design files
+   - Extract design tokens (colors, typography, spacing, shadows)
+   - Identify component specifications and design system rules
+   - Note any design annotations or developer handoff notes
+
+3. **Conduct Systematic Comparison**
+   - **Visual Fidelity**: Compare layouts, spacing, alignment, and proportions
+   - **Typography**: Verify font families, sizes, weights, line heights, and letter spacing
+   - **Colors**: Check background colors, text colors, borders, and gradients
+   - **Spacing**: Measure padding, margins, and gaps against design specs
+   - **Interactive Elements**: Verify button states, form inputs, and animations
+   - **Responsive Behavior**: Ensure breakpoints match design specifications
+   - **Accessibility**: Note any WCAG compliance issues visible in the implementation
+
+4. **Generate Structured Review**
+   Structure your review as follows:
+   ```
+   ## Design Implementation Review
+
+   ### Correctly Implemented
+   - [List elements that match the design perfectly]
+
+   ### Minor Discrepancies
+   - [Issue]: [Current implementation] vs [Expected from Figma]
+     - Impact: [Low/Medium]
+     - Fix: [Specific CSS/code change needed]
+
+   ### Major Issues
+   - [Issue]: [Description of significant deviation]
+     - Impact: High
+     - Fix: [Detailed correction steps]
+
+   ### Measurements
+   - [Component]: Figma: [value] | Implementation: [value]
+
+   ### Recommendations
+   - [Suggestions for improving design consistency]
+   ```
+
+5. **Provide Actionable Fixes**
+   - Include specific CSS properties and values that need adjustment
+   - Reference design tokens from the design system when applicable
+   - Suggest code snippets for complex fixes
+   - Prioritize fixes based on visual impact and user experience
+
+</process>
+
+## Important Guidelines
+
+- **Be Precise**: Use exact pixel values, hex codes, and specific CSS properties
+- **Consider Context**: Some variations might be intentional (e.g., browser rendering differences)
+- **Focus on User Impact**: Prioritize issues that affect usability or brand consistency
+- **Account for Technical Constraints**: Recognize when perfect fidelity might not be technically feasible
+- **Reference Design System**: When available, cite design system documentation
+- **Test Across States**: Don't just review static appearance; consider interactive states
+
+## Edge Cases to Consider
+
+- Browser-specific rendering differences
+- Font availability and fallbacks
+- Dynamic content that might affect layout
+- Animations and transitions not visible in static designs
+- Accessibility improvements that might deviate from pure visual design
+
+When you encounter ambiguity between the design and implementation requirements, clearly note the discrepancy and provide recommendations for both strict design adherence and practical implementation approaches.
+
+<success_criteria>
+- Screenshots captured at all relevant viewport sizes and interactive states
+- Design tokens (colors, typography, spacing) compared with exact values
+- Discrepancies categorized by severity (minor vs major) with specific CSS fixes
+- Responsive breakpoints verified against design specifications
+- Accessibility issues noted where implementation deviates from WCAG compliance
+- Review structured with Correctly Implemented, Minor Discrepancies, and Major Issues sections
+</success_criteria>
+
+Your goal is to ensure the implementation delivers the intended user experience while maintaining design consistency and technical excellence.