@lavralabs/lavra 0.7.0

package/plugins/lavra/gemini/skills/andrew-kane-gem-writer/SKILL.md

@@ -0,0 +1,188 @@
+<!-- Generated by lavra-compound v0.6.0 -->
+<!-- Source: andrew-kane-gem-writer/SKILL.md -->
+<!-- DO NOT EDIT - changes will be overwritten on next install -->
+
+---
+name: andrew-kane-gem-writer
+description: This skill should be used when writing Ruby gems following Andrew Kane's proven patterns and philosophy. It applies when creating new Ruby gems, refactoring existing gems, designing gem APIs, or when clean, minimal, production-ready Ruby library code is needed. Triggers on requests like "create a gem", "write a Ruby library", "design a gem API", or mentions of Andrew Kane's style.
+---
+
+# Andrew Kane Gem Writer
+
+Write Ruby gems following Andrew Kane's battle-tested patterns from 100+ gems with 374M+ downloads (Searchkick, PgHero, Chartkick, Strong Migrations, Lockbox, Ahoy, Blazer, Groupdate, Neighbor, Blind Index).
+
+## Core Philosophy
+
+**Simplicity over cleverness.** Zero or minimal dependencies. Explicit code over metaprogramming. Rails integration without Rails coupling. Every pattern serves production use cases.
+
+## Entry Point Structure
+
+Every gem follows this exact pattern in `lib/gemname.rb`:
+
+```ruby
+# 1. Dependencies (stdlib preferred)
+require "forwardable"
+
+# 2. Internal modules
+require_relative "gemname/model"
+require_relative "gemname/version"
+
+# 3. Conditional Rails (CRITICAL - never require Rails directly)
+require_relative "gemname/railtie" if defined?(Rails)
+
+# 4. Module with config and errors
+module GemName
+  class Error < StandardError; end
+  class InvalidConfigError < Error; end
+
+  class << self
+    attr_accessor :timeout, :logger
+    attr_writer :client
+  end
+
+  self.timeout = 10  # Defaults set immediately
+end
+```
+
+## Class Macro DSL Pattern
+
+The signature Kane pattern—single method call configures everything:
+
+```ruby
+# Usage
+class Product < ApplicationRecord
+  searchkick word_start: [:name]
+end
+
+# Implementation
+module GemName
+  module Model
+    def gemname(**options)
+      unknown = options.keys - KNOWN_KEYWORDS
+      raise ArgumentError, "unknown keywords: #{unknown.join(", ")}" if unknown.any?
+
+      mod = Module.new
+      mod.module_eval do
+        define_method :some_method do
+          # implementation
+        end unless method_defined?(:some_method)
+      end
+      include mod
+
+      class_eval do
+        cattr_reader :gemname_options, instance_reader: false
+        class_variable_set :@@gemname_options, options.dup
+      end
+    end
+  end
+end
+```
+
+## Rails Integration
+
+**Always use `ActiveSupport.on_load`—never require Rails gems directly:**
+
+```ruby
+# WRONG
+require "active_record"
+ActiveRecord::Base.include(MyGem::Model)
+
+# CORRECT
+ActiveSupport.on_load(:active_record) do
+  extend GemName::Model
+end
+
+# Use prepend for behavior modification
+ActiveSupport.on_load(:active_record) do
+  ActiveRecord::Migration.prepend(GemName::Migration)
+end
+```
+
+## Configuration Pattern
+
+Use `class << self` with `attr_accessor`, not Configuration objects:
+
+```ruby
+module GemName
+  class << self
+    attr_accessor :timeout, :logger
+    attr_writer :master_key
+  end
+
+  def self.master_key
+    @master_key ||= ENV["GEMNAME_MASTER_KEY"]
+  end
+
+  self.timeout = 10
+  self.logger = nil
+end
+```
+
+## Error Handling
+
+Simple hierarchy with informative messages:
+
+```ruby
+module GemName
+  class Error < StandardError; end
+  class ConfigError < Error; end
+  class ValidationError < Error; end
+end
+
+# Validate early with ArgumentError
+def initialize(key:)
+  raise ArgumentError, "Key must be 32 bytes" unless key&.bytesize == 32
+end
+```
+
+## Testing (Minitest Only)
+
+```ruby
+# test/test_helper.rb
+require "bundler/setup"
+Bundler.require(:default)
+require "minitest/autorun"
+require "minitest/pride"
+
+# test/model_test.rb
+class ModelTest < Minitest::Test
+  def test_basic_functionality
+    assert_equal expected, actual
+  end
+end
+```
+
+## Gemspec Pattern
+
+Zero runtime dependencies when possible:
+
+```ruby
+Gem::Specification.new do |spec|
+  spec.name = "gemname"
+  spec.version = GemName::VERSION
+  spec.required_ruby_version = ">= 3.1"
+  spec.files = Dir["*.{md,txt}", "{lib}/**/*"]
+  spec.require_path = "lib"
+  # NO add_dependency lines - dev deps go in Gemfile
+end
+```
+
+## Anti-Patterns to Avoid
+
+- `method_missing` (use `define_method` instead)
+- Configuration objects (use class accessors)
+- `@@class_variables` (use `class << self`)
+- Requiring Rails gems directly
+- Many runtime dependencies
+- Committing Gemfile.lock in gems
+- RSpec (use Minitest)
+- Heavy DSLs (prefer explicit Ruby)
+
+## Reference Files
+
+For deeper patterns, see:
+- **[references/module-organization.md](references/module-organization.md)** - Directory layouts, method decomposition
+- **[references/rails-integration.md](references/rails-integration.md)** - Railtie, Engine, on_load patterns
+- **[references/database-adapters.md](references/database-adapters.md)** - Multi-database support patterns
+- **[references/testing-patterns.md](references/testing-patterns.md)** - Multi-version testing, CI setup
+- **[references/resources.md](references/resources.md)** - Links to Kane's repos and articles

package/plugins/lavra/gemini/skills/beads-knowledge/SKILL.md

@@ -0,0 +1,464 @@
+<!-- Generated by lavra-compound v0.6.0 -->
+<!-- Source: lavra-knowledge/SKILL.md -->
+<!-- DO NOT EDIT - changes will be overwritten on next install -->
+
+---
+name: lavra-knowledge
+description: "Capture solved problems as knowledge entries in JSONL format for fast recall. Use when a problem has been solved and the solution should be preserved for future sessions."
+allowed-tools: "- Read # Parse conversation context
+  - Write # Append to knowledge.jsonl
+  - Bash # Run bd commands, search knowledge
+  - Grep # Search existing knowledge"
+preconditions: "- Problem has been solved (not in-progress)
+  - Solution has been verified working"
+disable-model-invocation: true
+---
+
+# lavra-knowledge Skill
+
+**Purpose:** Capture solved problems as structured JSONL entries in `.lavra/memory/knowledge.jsonl` and as bead comments, building a searchable knowledge base that auto-recall injects into future sessions.
+
+## Overview
+
+This skill captures problem solutions immediately after confirmation, creating structured knowledge entries that:
+- Are stored in `.lavra/memory/knowledge.jsonl` for auto-recall search
+- Are logged as bead comments for traceability back to specific work items
+- Use the five knowledge prefixes: LEARNED, DECISION, FACT, PATTERN, INVESTIGATION
+
+**Organization:** Append-only JSONL file. Each solved problem produces one or more knowledge entries. The auto-recall hook (`auto-recall.sh`) searches these entries by keyword and injects relevant ones at session start.
+
+---
+
+<critical_sequence name="knowledge-capture" enforce_order="strict">
+
+## 7-Step Process
+
+<step number="1" required="true">
+### Step 1: Detect Confirmation
+
+**Auto-invoke after phrases:**
+
+- "that worked"
+- "it's fixed"
+- "working now"
+- "problem solved"
+- "that did it"
+
+**OR manual invocation.**
+
+**Non-trivial problems only:**
+
+- Multiple investigation attempts needed
+- Tricky debugging that took time
+- Non-obvious solution
+- Future sessions would benefit
+
+**Skip for:**
+
+- Simple typos
+- Obvious syntax errors
+- Trivial fixes immediately corrected
+</step>
+
+<step number="2" required="true" depends_on="1">
+### Step 2: Gather Context
+
+Extract from conversation history:
+
+**Required information:**
+
+- **Area/module**: Which part of the codebase had the problem
+- **Symptom**: Observable error/behavior (exact error messages)
+- **Investigation attempts**: What didn't work and why
+- **Root cause**: Technical explanation of actual problem
+- **Solution**: What fixed it (code/config changes)
+- **Prevention**: How to avoid in future
+
+**BLOCKING REQUIREMENT:** If critical context is missing (area, exact error, or resolution steps), ask user and WAIT for response before proceeding to Step 3:
+
+```
+I need a few details to document this properly:
+
+1. Which area/module had this issue?
+2. What was the exact error message or symptom?
+3. What fixed it?
+
+[Continue after user provides details]
+```
+</step>
+
+<step number="3" required="false" depends_on="2">
+### Step 3: Check Existing Knowledge
+
+Search knowledge.jsonl for similar issues:
+
+```bash
+# Search by error message keywords
+grep "exact error phrase" .lavra/memory/knowledge.jsonl
+
+# Search using recall script if available
+.lavra/memory/recall.sh "keyword1 keyword2"
+```
+
+**IF similar knowledge found:**
+
+Present decision options:
+
+```
+Found similar knowledge entry:
+  [key]: [content summary]
+
+What's next?
+1. Create new entries anyway (recommended if different root cause)
+2. Skip (this is a duplicate)
+3. Create new entries with cross-reference
+
+Choose (1-3): _
+```
+
+WAIT for user response.
+
+**ELSE** (no similar knowledge found):
+
+Proceed directly to Step 4.
+</step>
+
+<step number="4" required="true" depends_on="2">
+### Step 4: Determine Knowledge Type
+
+Classify the solution into one or more knowledge prefixes:
+
+| Prefix | Use When | Example |
+|--------|----------|---------|
+| LEARNED | Discovered something non-obvious through debugging | "LEARNED: OAuth redirect URI must match exactly including trailing slash" |
+| DECISION | Made an architectural or implementation choice | "DECISION: Use connection pooling instead of per-request connections because..." |
+| FACT | Confirmed a factual constraint or requirement | "FACT: PostgreSQL JSONB columns require explicit casting for array operations" |
+| PATTERN | Identified a recurring pattern (good or bad) | "PATTERN: Always check for nil before accessing nested hash keys in API responses" |
+| INVESTIGATION | Documented an investigation path for future reference | "INVESTIGATION: Debugged memory leak - profiler showed retained objects from..." |
+
+Most solved problems produce 1-3 entries. A complex debugging session might produce:
+- 1 LEARNED (the key insight)
+- 1 PATTERN (the prevention rule)
+- 1 INVESTIGATION (the debugging path for future reference)
+</step>
+
+<step number="5" required="true" depends_on="4" blocking="true">
+### Step 5: Validate JSONL Entry
+
+**CRITICAL:** All knowledge entries must conform to the JSONL schema.
+
+<validation_gate name="jsonl-schema" blocking="true">
+
+**Required fields for each entry:**
+
+```json
+{
+  "key": "lowercase-hyphen-separated-unique-key",
+  "type": "learned|decision|fact|pattern|investigation",
+  "content": "Clear, specific description of the knowledge",
+  "source": "user|agent|subagent",
+  "tags": ["tag1", "tag2"],
+  "ts": 1706918400,
+  "bead": "BD-001"
+}
+```
+
+**Validation rules:**
+
+1. **key**: Must be lowercase, hyphen-separated, unique, descriptive (e.g., `learned-oauth-redirect-must-match-exactly`)
+2. **type**: Must be one of: `learned`, `decision`, `fact`, `pattern`, `investigation`
+3. **content**: Must be specific and searchable (no vague descriptions)
+4. **source**: Must be `user`, `agent`, or `subagent`
+5. **tags**: Array of lowercase keywords for search (auto-detected from content where possible)
+6. **ts**: Unix timestamp (current time)
+7. **bead**: Bead ID if working on a specific bead, or empty string if none
+
+**Auto-tagging:** Extract keywords from content matching known domains:
+- auth, oauth, jwt, session -> "auth"
+- database, postgres, sql, migration -> "database"
+- react, component, hook, state -> "react"
+- api, endpoint, request, response -> "api"
+- test, spec, fixture, mock -> "testing"
+- performance, memory, cache, query -> "performance"
+- deploy, ci, docker, build -> "devops"
+- config, env, settings -> "config"
+
+**BLOCK if validation fails:**
+
+```
+JSONL validation failed:
+
+Errors:
+- key: must be lowercase-hyphen-separated, got "MyKey"
+- type: must be one of [learned, decision, fact, pattern, investigation], got "bug"
+- content: too vague - must be specific and searchable
+
+Please provide corrected values.
+```
+
+**GATE ENFORCEMENT:** Do NOT proceed to Step 6 until all entries pass validation.
+
+</validation_gate>
+</step>
+
+<step number="6" required="true" depends_on="5">
+### Step 6: Write Knowledge Entries
+
+**Append entries to knowledge.jsonl:**
+
+```bash
+# Append each validated entry as a single JSON line
+echo '{"key":"learned-oauth-redirect-must-match","type":"learned","content":"OAuth redirect URI must match exactly including trailing slash","source":"agent","tags":["auth","oauth","security"],"ts":1706918400,"bead":"BD-001"}' >> .lavra/memory/knowledge.jsonl
+```
+
+**Log as bead comments (if bead ID available):**
+
+For each knowledge entry, also log it as a bead comment using the appropriate prefix:
+
+```bash
+bd comments add BD-001 "LEARNED: OAuth redirect URI must match exactly including trailing slash"
+bd comments add BD-001 "PATTERN: Always verify OAuth redirect URIs match exactly, including protocol and trailing slash"
+```
+
+**Handle rotation:** If knowledge.jsonl exceeds 1000 lines after appending:
+1. Move first 500 lines to `knowledge.archive.jsonl`
+2. Keep remaining lines as new `knowledge.jsonl`
+
+```bash
+LINE_COUNT=$(wc -l < .lavra/memory/knowledge.jsonl)
+if [ "$LINE_COUNT" -gt 1000 ]; then
+  head -500 .lavra/memory/knowledge.jsonl >> .lavra/memory/knowledge.archive.jsonl
+  tail -n +501 .lavra/memory/knowledge.jsonl > .lavra/memory/knowledge.jsonl.tmp
+  mv .lavra/memory/knowledge.jsonl.tmp .lavra/memory/knowledge.jsonl
+fi
+```
+</step>
+
+<step number="7" required="false" depends_on="6">
+### Step 7: Cross-Reference & Pattern Detection
+
+If similar knowledge found in Step 3:
+
+**Add cross-reference tag:**
+Include the key of the related entry in the tags array (e.g., `"tags": ["auth", "see-also:learned-oauth-token-expiry"]`).
+
+**Detect recurring patterns:**
+
+If 3+ entries share the same tags or describe similar issues, suggest creating a PATTERN entry that synthesizes the recurring theme:
+
+```
+Detected recurring pattern: 3 entries related to "auth" + "redirect"
+
+Suggest creating a PATTERN entry?
+1. Yes - create synthesized pattern entry
+2. No - entries are distinct enough
+
+Choose (1-2): _
+```
+</step>
+
+</critical_sequence>
+
+---
+
+<decision_gate name="post-capture" wait_for_user="true">
+
+## Decision Menu After Capture
+
+After successful knowledge capture, present options and WAIT for user response:
+
+```
+Knowledge captured successfully.
+
+Entries added:
+- [key1]: [content summary]
+- [key2]: [content summary]
+
+Bead comments logged: [Yes/No - BD-XXX]
+
+What's next?
+1. Continue workflow (recommended)
+2. View captured entries
+3. Search related knowledge
+4. Add more entries for this solution
+5. Other
+```
+
+**Handle responses:**
+
+**Option 1: Continue workflow**
+- Return to calling skill/workflow
+- Knowledge capture is complete
+
+**Option 2: View captured entries**
+- Display the JSONL entries that were written
+- Present decision menu again
+
+**Option 3: Search related knowledge**
+- Run recall search with the tags from the new entries
+- Display related knowledge
+- Present decision menu again
+
+**Option 4: Add more entries**
+- Return to Step 4 to classify additional knowledge
+- Useful when the solution reveals multiple insights
+
+**Option 5: Other**
+- Ask what they'd like to do
+
+</decision_gate>
+
+---
+
+<integration_protocol>
+
+## Integration Points
+
+**Invoked by:**
+- Manual invocation in conversation after solution confirmed
+- Can be triggered by detecting confirmation phrases like "that worked", "it's fixed", etc.
+- Called from `/lavra-work` and `/lavra-review` workflows
+
+**Works with:**
+- `auto-recall.sh` hook reads from knowledge.jsonl at session start
+- `memory-capture.sh` hook captures knowledge from `bd comments add` commands
+- `recall.sh` script provides manual search
+
+**Data flow:**
+1. This skill writes structured entries to `.lavra/memory/knowledge.jsonl`
+2. This skill also logs comments via `bd comments add` (which triggers `memory-capture.sh`)
+3. At next session start, `auto-recall.sh` searches knowledge.jsonl and injects relevant entries
+
+</integration_protocol>
+
+---
+
+<success_criteria>
+
+## Success Criteria
+
+Knowledge capture is successful when ALL of the following are true:
+
+- All JSONL entries have valid schema (required fields, correct types)
+- Entries appended to `.lavra/memory/knowledge.jsonl`
+- Bead comments logged via `bd comments add` (if bead ID available)
+- Content is specific and searchable (not vague)
+- Tags are appropriate for future recall
+- User presented with decision menu and action confirmed
+
+</success_criteria>
+
+---
+
+## Error Handling
+
+**Missing context:**
+
+- Ask user for missing details
+- Don't proceed until critical info provided
+
+**JSONL validation failure:**
+
+- Show specific errors
+- Present retry with corrected values
+- BLOCK until valid
+
+**Missing bead ID:**
+
+- Knowledge can still be captured to knowledge.jsonl
+- Skip `bd comments add` step
+- Warn: "No active bead - knowledge saved to JSONL only, not linked to a bead"
+
+**Knowledge.jsonl doesn't exist:**
+
+- Create it: `touch .lavra/memory/knowledge.jsonl`
+- Continue normally
+
+---
+
+## Execution Guidelines
+
+**MUST do:**
+- Validate JSONL entries (BLOCK if invalid per Step 5 validation gate)
+- Extract exact error messages from conversation
+- Include specific, searchable content
+- Use `bd comments add` with knowledge prefixes when bead ID is available
+- Auto-tag based on content keywords
+
+**MUST NOT do:**
+- Skip JSONL validation
+- Use vague descriptions (not searchable for auto-recall)
+- Create markdown files in docs/solutions/ (this is NOT compound-docs)
+- Write entries with missing required fields
+
+---
+
+## Quality Guidelines
+
+**Good knowledge entries have:**
+
+- Specific, searchable content (exact error messages, specific techniques)
+- Appropriate type classification (LEARNED vs FACT vs PATTERN etc.)
+- Relevant tags for future keyword-based recall
+- Clear cause-and-effect (not just "what" but "why")
+- Prevention guidance where applicable
+
+**Avoid:**
+
+- Vague content ("something was wrong with auth")
+- Missing technical details ("fixed the code")
+- Overly broad tags ("code", "bug")
+- Duplicate content across entries (each entry should add unique value)
+
+---
+
+## Example Scenario
+
+**User:** "That worked! The N+1 query is fixed."
+
+**Skill activates:**
+
+1. **Detect confirmation:** "That worked!" triggers auto-invoke
+2. **Gather context:**
+   - Area: Database queries in order processing
+   - Symptom: Order listing taking >5 seconds, N+1 query when loading items
+   - Failed attempts: Added pagination (didn't help)
+   - Solution: Added eager loading with `.includes(:items)` on Order model
+   - Root cause: Missing eager loading causing separate query per order item
+3. **Check existing:** No similar knowledge found
+4. **Determine type:**
+   - LEARNED: The key insight about eager loading
+   - PATTERN: Prevention rule for future queries
+5. **Validate entries:**
+   ```json
+   {"key":"learned-n-plus-one-order-items-eager-load","type":"learned","content":"Order listing N+1 query fixed by adding .includes(:items) to Order model scope. Missing eager loading caused separate DB query per order item, taking >5 seconds for 100+ orders.","source":"agent","tags":["database","performance","n-plus-one","eager-loading"],"ts":1706918400,"bead":"BD-042"}
+   {"key":"pattern-always-check-eager-loading-on-associations","type":"pattern","content":"When listing parent records that display child data, always use .includes() for associations. Check with bullet gem or query logs. Without eager loading, N records = N+1 queries.","source":"agent","tags":["database","performance","n-plus-one","eager-loading","prevention"],"ts":1706918401,"bead":"BD-042"}
+   ```
+   Valid.
+6. **Write entries:**
+   - Appended to `.lavra/memory/knowledge.jsonl`
+   - Logged bead comments:
+     ```bash
+     bd comments add BD-042 "LEARNED: Order listing N+1 query fixed by adding .includes(:items). Missing eager loading caused separate DB query per order item."
+     bd comments add BD-042 "PATTERN: When listing parent records that display child data, always use .includes() for associations. Check with bullet gem or query logs."
+     ```
+7. **Cross-reference:** None needed (no similar knowledge)
+
+**Output:**
+
+```
+Knowledge captured successfully.
+
+Entries added:
+- learned-n-plus-one-order-items-eager-load: Order listing N+1 query fixed by adding .includes(:items)...
+- pattern-always-check-eager-loading-on-associations: When listing parent records...
+
+Bead comments logged: Yes - BD-042
+
+What's next?
+1. Continue workflow (recommended)
+2. View captured entries
+3. Search related knowledge
+4. Add more entries for this solution
+5. Other
+```