@lavralabs/lavra 0.7.0

package/plugins/lavra/cortex/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/cortex/skills/brainstorming/SKILL.md

@@ -0,0 +1,197 @@
+<!-- Generated by lavra v0.6.0 -->
+<!-- Source: brainstorming/SKILL.md -->
+<!-- DO NOT EDIT - changes will be overwritten on next install -->
+
+---
+name: brainstorming
+description: This skill should be used before implementing features, building components, or making changes. It guides exploring user intent, approaches, and design decisions before planning. Triggers on "let's brainstorm", "help me think through", "what should we build", "explore approaches", ambiguous feature requests, or when the user's request has multiple valid interpretations that need clarification.
+---
+
+# Brainstorming
+
+This skill provides detailed process knowledge for effective brainstorming sessions that clarify **WHAT** to build before diving into **HOW** to build it.
+
+## When to Use This Skill
+
+Brainstorming is valuable when:
+- Requirements are unclear or ambiguous
+- Multiple approaches could solve the problem
+- Trade-offs need to be explored with the user
+- The user hasn't fully articulated what they want
+- The feature scope needs refinement
+
+Brainstorming can be skipped when:
+- Requirements are explicit and detailed
+- The user knows exactly what they want
+- The task is a straightforward bug fix or well-defined change
+
+## Core Process
+
+### Phase 0: Assess Requirement Clarity
+
+Before diving into questions, assess whether brainstorming is needed.
+
+**Signals that requirements are clear:**
+- User provided specific acceptance criteria
+- User referenced existing patterns to follow
+- User described exact behavior expected
+- Scope is constrained and well-defined
+
+**Signals that brainstorming is needed:**
+- User used vague terms ("make it better", "add something like")
+- Multiple reasonable interpretations exist
+- Trade-offs haven't been discussed
+- User seems unsure about the approach
+
+If requirements are clear, suggest: "Your requirements seem clear. Consider proceeding directly to planning or implementation."
+
+### Phase 1: Understand the Idea
+
+Ask questions **one at a time** to understand the user's intent. Avoid overwhelming with multiple questions.
+
+**Question Techniques:**
+
+1. **Prefer multiple choice when natural options exist**
+   - Good: "Should the notification be: (a) email only, (b) in-app only, or (c) both?"
+   - Avoid: "How should users be notified?"
+
+2. **Start broad, then narrow**
+   - First: What is the core purpose?
+   - Then: Who are the users?
+   - Finally: What constraints exist?
+
+3. **Validate assumptions explicitly**
+   - "I'm assuming users will be logged in. Is that correct?"
+
+4. **Ask about success criteria early**
+   - "How will you know this feature is working well?"
+
+**Key Topics to Explore:**
+
+| Topic | Example Questions |
+|-------|-------------------|
+| Purpose | What problem does this solve? What's the motivation? |
+| Users | Who uses this? What's their context? |
+| Constraints | Any technical limitations? Timeline? Dependencies? |
+| Success | How will you measure success? What's the happy path? |
+| Edge Cases | What shouldn't happen? Any error states to consider? |
+| Existing Patterns | Are there similar features in the codebase to follow? |
+
+**Exit Condition:** Continue until the idea is clear OR user says "proceed" or "let's move on"
+
+### Phase 2: Explore Approaches
+
+After understanding the idea, propose 2-3 concrete approaches.
+
+**Structure for Each Approach:**
+
+```markdown
+### Approach A: [Name]
+
+[2-3 sentence description]
+
+**Pros:**
+- [Benefit 1]
+- [Benefit 2]
+
+**Cons:**
+- [Drawback 1]
+- [Drawback 2]
+
+**Best when:** [Circumstances where this approach shines]
+```
+
+**Guidelines:**
+- Lead with a recommendation and explain why
+- Be honest about trade-offs
+- Consider YAGNI--simpler is usually better
+- Reference codebase patterns when relevant
+
+### Phase 3: Capture the Design
+
+Summarize key decisions as bead comments to persist the brainstorming output.
+
+**Capture key decisions and investigation results using bead comments:**
+
+For each significant decision or finding, log it to the active bead:
+
+```bash
+# Log the chosen approach
+bd comments add {BEAD_ID} "DECISION: Chose [approach name] because [rationale]. Alternatives considered: [list]"
+
+# Log key investigation findings
+bd comments add {BEAD_ID} "INVESTIGATION: Explored [topic]. Found that [key finding]. This means [implication]."
+
+# Log important facts discovered during brainstorming
+bd comments add {BEAD_ID} "FACT: [Constraint or requirement discovered during brainstorming]"
+```
+
+**If no active bead exists**, present a summary in this format:
+
+```markdown
+## What We're Building
+[Concise description--1-2 paragraphs max]
+
+## Why This Approach
+[Brief explanation of approaches considered and why this one was chosen]
+
+## Key Decisions
+- [Decision 1]: [Rationale]
+- [Decision 2]: [Rationale]
+
+## Open Questions
+- [Any unresolved questions for the planning phase]
+```
+
+### Phase 4: Handoff
+
+Present clear options for what to do next:
+
+1. **Proceed to planning** -> Run `/lavra-plan`
+2. **Refine further** -> Continue exploring the design
+3. **Done for now** -> User will return later
+
+## YAGNI Principles
+
+During brainstorming, actively resist complexity:
+
+- **Don't design for hypothetical future requirements**
+- **Choose the simplest approach that solves the stated problem**
+- **Prefer boring, proven patterns over clever solutions**
+- **Ask "Do we really need this?" when complexity emerges**
+- **Defer decisions that don't need to be made now**
+
+## Incremental Validation
+
+Keep sections short--200-300 words maximum. After each section of output, pause to validate understanding:
+
+- "Does this match what you had in mind?"
+- "Any adjustments before we continue?"
+- "Is this the direction you want to go?"
+
+This prevents wasted effort on misaligned designs.
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Better Approach |
+|--------------|-----------------|
+| Asking 5 questions at once | Ask one at a time |
+| Jumping to implementation details | Stay focused on WHAT, not HOW |
+| Proposing overly complex solutions | Start simple, add complexity only if needed |
+| Ignoring existing codebase patterns | Research what exists first |
+| Making assumptions without validating | State assumptions explicitly and confirm |
+| Creating lengthy design documents | Keep it concise--details go in the plan |
+
+## Integration with Planning
+
+Brainstorming answers **WHAT** to build:
+- Requirements and acceptance criteria
+- Chosen approach and rationale
+- Key decisions and trade-offs
+
+Planning answers **HOW** to build it:
+- Implementation steps and file changes
+- Technical details and code patterns
+- Testing strategy and verification
+
+When brainstorm output exists (as bead comments), `/lavra-plan` should detect it and use it as input, skipping its own idea refinement phase.

package/plugins/lavra/cortex/skills/create-agent-skills/SKILL.md

@@ -0,0 +1,304 @@
+<!-- Generated by lavra v0.6.0 -->
+<!-- Source: create-agent-skills/SKILL.md -->
+<!-- DO NOT EDIT - changes will be overwritten on next install -->
+
+---
+name: creating-agent-skills
+description: "Expert guidance for creating, writing, and refining Claude Code Skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices."
+disable-model-invocation: true
+---
+
+# Creating Agent Skills
+
+This skill teaches how to create effective Claude Code Skills following Anthropic's official specification.
+
+## Core Principles
+
+### 1. Skills Are Prompts
+
+All prompting best practices apply. Be clear, be direct. Assume Claude is smart - only add context Claude doesn't have.
+
+### 2. Standard Markdown Format
+
+Use YAML frontmatter + markdown body. **No XML tags** - use standard markdown headings.
+
+```markdown
+---
+name: my-skill-name
+description: What it does and when to use it
+---
+
+# My Skill Name
+
+## Quick Start
+Immediate actionable guidance...
+
+## Instructions
+Step-by-step procedures...
+
+## Examples
+Concrete usage examples...
+```
+
+### 3. Progressive Disclosure
+
+Keep SKILL.md under 500 lines. Split detailed content into reference files. Load only what's needed.
+
+```
+my-skill/
+├── SKILL.md              # Entry point (required)
+├── reference.md          # Detailed docs (loaded when needed)
+├── examples.md           # Usage examples
+└── scripts/              # Utility scripts (executed, not loaded)
+```
+
+### 4. Effective Descriptions
+
+The description field enables skill discovery. Include both what the skill does AND when to use it. Write in third person.
+
+**Good:**
+```yaml
+description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+```
+
+**Bad:**
+```yaml
+description: Helps with documents
+```
+
+## Skill Structure
+
+### Required Frontmatter
+
+| Field | Required | Max Length | Description |
+|-------|----------|------------|-------------|
+| `name` | Yes | 64 chars | Lowercase letters, numbers, hyphens only |
+| `description` | Yes | 1024 chars | What it does AND when to use it |
+| `allowed-tools` | No | - | Tools Claude can use without asking |
+| `model` | No | - | Specific model to use |
+
+### Naming Conventions
+
+Use **gerund form** (verb + -ing) for skill names:
+
+- `processing-pdfs`
+- `analyzing-spreadsheets`
+- `generating-commit-messages`
+- `reviewing-code`
+
+Avoid: `helper`, `utils`, `tools`, `anthropic-*`, `claude-*`
+
+### Body Structure
+
+Use standard markdown headings:
+
+```markdown
+# Skill Name
+
+## Quick Start
+Fastest path to value...
+
+## Instructions
+Core guidance Claude follows...
+
+## Examples
+Input/output pairs showing expected behavior...
+
+## Advanced Features
+Additional capabilities (link to reference files)...
+
+## Guidelines
+Rules and constraints...
+```
+
+## What Would You Like To Do?
+
+1. **Create new skill** - Build from scratch
+2. **Audit existing skill** - Check against best practices
+3. **Add component** - Add workflow/reference/example
+4. **Get guidance** - Understand skill design
+
+## Creating a New Skill
+
+### Step 1: Choose Type
+
+**Simple skill (single file):**
+- Under 500 lines
+- Self-contained guidance
+- No complex workflows
+
+**Progressive disclosure skill (multiple files):**
+- SKILL.md as overview
+- Reference files for detailed docs
+- Scripts for utilities
+
+### Step 2: Create SKILL.md
+
+```markdown
+---
+name: your-skill-name
+description: [What it does]. Use when [trigger conditions].
+---
+
+# Your Skill Name
+
+## Quick Start
+
+[Immediate actionable example]
+
+```[language]
+[Code example]
+```
+
+## Instructions
+
+[Core guidance]
+
+## Examples
+
+**Example 1:**
+Input: [description]
+Output:
+```
+[result]
+```
+
+## Guidelines
+
+- [Constraint 1]
+- [Constraint 2]
+```
+
+### Step 3: Add Reference Files (If Needed)
+
+Link from SKILL.md to detailed content:
+
+```markdown
+For API reference, see [REFERENCE.md](REFERENCE.md).
+For form filling guide, see [FORMS.md](FORMS.md).
+```
+
+Keep references **one level deep** from SKILL.md.
+
+### Step 4: Add Scripts (If Needed)
+
+Scripts execute without loading into context:
+
+```markdown
+## Utility Scripts
+
+Extract fields:
+```bash
+python scripts/analyze.py input.pdf > fields.json
+```
+```
+
+### Step 5: Test With Real Usage
+
+1. Test with actual tasks, not test scenarios
+2. Observe where Claude struggles
+3. Refine based on real behavior
+4. Test with Haiku, Sonnet, and Opus
+
+## Auditing Existing Skills
+
+Check against this rubric:
+
+- [ ] Valid YAML frontmatter (name + description)
+- [ ] Description includes trigger keywords
+- [ ] Uses standard markdown headings (not XML tags)
+- [ ] SKILL.md under 500 lines
+- [ ] References one level deep
+- [ ] Examples are concrete, not abstract
+- [ ] Consistent terminology
+- [ ] No time-sensitive information
+- [ ] Scripts handle errors explicitly
+
+## Common Patterns
+
+### Template Pattern
+
+Provide output templates for consistent results:
+
+```markdown
+## Report Template
+
+```markdown
+# [Analysis Title]
+
+## Executive Summary
+[One paragraph overview]
+
+## Key Findings
+- Finding 1
+- Finding 2
+
+## Recommendations
+1. [Action item]
+2. [Action item]
+```
+```
+
+### Workflow Pattern
+
+For complex multi-step tasks:
+
+```markdown
+## Migration Workflow
+
+Copy this checklist:
+
+```
+- [ ] Step 1: Backup database
+- [ ] Step 2: Run migration script
+- [ ] Step 3: Validate output
+- [ ] Step 4: Update configuration
+```
+
+**Step 1: Backup database**
+Run: `./scripts/backup.sh`
+...
+```
+
+### Conditional Pattern
+
+Guide through decision points:
+
+```markdown
+## Choose Your Approach
+
+**Creating new content?** Follow "Creation workflow" below.
+**Editing existing?** Follow "Editing workflow" below.
+```
+
+## Anti-Patterns to Avoid
+
+- **XML tags in body** - Use markdown headings instead
+- **Vague descriptions** - Be specific with trigger keywords
+- **Deep nesting** - Keep references one level from SKILL.md
+- **Too many options** - Provide a default with escape hatch
+- **Windows paths** - Always use forward slashes
+- **Punting to Claude** - Scripts should handle errors
+- **Time-sensitive info** - Use "old patterns" section instead
+
+## Reference Files
+
+For detailed guidance, see:
+
+- [official-spec.md](references/official-spec.md) - Anthropic's official skill specification
+- [best-practices.md](references/best-practices.md) - Skill authoring best practices
+
+## Success Criteria
+
+A well-structured skill:
+- Has valid YAML frontmatter with descriptive name and description
+- Uses standard markdown headings (not XML tags)
+- Keeps SKILL.md under 500 lines
+- Links to reference files for detailed content
+- Includes concrete examples with input/output pairs
+- Has been tested with real usage
+
+Sources:
+- [Agent Skills - Claude Code Docs](https://code.claude.com/docs/en/skills)
+- [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
+- [GitHub - anthropics/skills](https://github.com/anthropics/skills)