@lavralabs/lavra 0.7.0

package/plugins/lavra/cortex/commands/feature-video.md

@@ -0,0 +1,266 @@
+<!-- Generated by lavra-compound v0.6.0 -->
+<!-- Source: feature-video.md -->
+<!-- DO NOT EDIT - changes will be overwritten on next install -->
+
+---
+name: feature-video
+description: Record a video walkthrough of a feature and add it to the PR description
+argument-hint: "[PR number or 'current'] [optional: base URL, default localhost:3000]"
+disable-model-invocation: true
+---
+
+<objective>
+Record a video walkthrough demonstrating a feature, upload it, and add it to the PR description.
+</objective>
+
+<execution_context>
+
+**Arguments:** $ARGUMENTS
+
+Parse the input:
+- First argument: PR number or "current" (defaults to current branch's PR)
+- Second argument: Base URL (defaults to `http://localhost:3000`)
+
+```bash
+# Get PR number for current branch if needed
+gh pr view --json number -q '.number'
+```
+
+</execution_context>
+
+<context>
+
+### Prerequisites
+
+- Local development server running (e.g., `bin/dev`, `rails server`)
+- agent-browser CLI installed
+- Git repository with a PR to document
+- `ffmpeg` installed (for video conversion)
+- `rclone` configured (optional, for cloud upload - see rclone skill)
+
+### Setup
+
+**Check installation:**
+```bash
+command -v agent-browser >/dev/null 2>&1 && echo "Installed" || echo "NOT INSTALLED"
+```
+
+**Install if needed:**
+```bash
+npm install -g agent-browser && agent-browser install
+```
+
+See the `agent-browser` skill for detailed usage.
+
+</context>
+
+<process>
+
+## 1. Gather Feature Context
+
+**Get PR details:**
+```bash
+gh pr view [number] --json title,body,files,headRefName -q '.'
+```
+
+**Get changed files:**
+```bash
+gh pr view [number] --json files -q '.files[].path'
+```
+
+**Map files to testable routes:**
+
+| File Pattern | Route(s) |
+|-------------|----------|
+| `app/views/users/*` | `/users`, `/users/:id`, `/users/new` |
+| `app/controllers/settings_controller.rb` | `/settings` |
+| `app/javascript/controllers/*_controller.js` | Pages using that Stimulus controller |
+| `app/components/*_component.rb` | Pages rendering that component |
+
+## 2. Plan the Video Flow
+
+Before recording, create a shot list:
+
+1. **Opening shot**: Homepage or starting point (2-3 seconds)
+2. **Navigation**: How user gets to the feature
+3. **Feature demonstration**: Core functionality (main focus)
+4. **Edge cases**: Error states, validation, etc. (if applicable)
+5. **Success state**: Completed action/result
+
+Ask user to confirm or adjust the flow:
+
+```markdown
+**Proposed Video Flow**
+
+Based on PR #[number]: [title]
+
+1. Start at: /[starting-route]
+2. Navigate to: /[feature-route]
+3. Demonstrate:
+   - [Action 1]
+   - [Action 2]
+   - [Action 3]
+4. Show result: [success state]
+
+Estimated duration: ~[X] seconds
+
+Does this look right?
+1. Yes, start recording
+2. Modify the flow (describe changes)
+3. Add specific interactions to demonstrate
+```
+
+## 3. Setup Video Recording
+
+**Create videos directory:**
+```bash
+mkdir -p tmp/videos
+```
+
+**Recording approach: Use browser screenshots as frames**
+
+agent-browser captures screenshots at key moments, then combine into video using ffmpeg:
+
+```bash
+ffmpeg -framerate 2 -pattern_type glob -i 'tmp/screenshots/*.png' -vf "scale=1280:-1" tmp/videos/feature-demo.gif
+```
+
+## 4. Record the Walkthrough
+
+Execute the planned flow, capturing each step:
+
+**Step 1: Navigate to starting point**
+```bash
+agent-browser open "[base-url]/[start-route]"
+agent-browser wait 2000
+agent-browser screenshot tmp/screenshots/01-start.png
+```
+
+**Step 2: Perform navigation/interactions**
+```bash
+agent-browser snapshot -i  # Get refs
+agent-browser click @e1    # Click navigation element
+agent-browser wait 1000
+agent-browser screenshot tmp/screenshots/02-navigate.png
+```
+
+**Step 3: Demonstrate feature**
+```bash
+agent-browser snapshot -i  # Get refs for feature elements
+agent-browser click @e2    # Click feature element
+agent-browser wait 1000
+agent-browser screenshot tmp/screenshots/03-feature.png
+```
+
+**Step 4: Capture result**
+```bash
+agent-browser wait 2000
+agent-browser screenshot tmp/screenshots/04-result.png
+```
+
+**Create video/GIF from screenshots:**
+
+```bash
+# Create directories
+mkdir -p tmp/videos tmp/screenshots
+
+# Create MP4 video (RECOMMENDED - better quality, smaller size)
+# -framerate 0.5 = 2 seconds per frame (slower playback)
+# -framerate 1 = 1 second per frame
+ffmpeg -y -framerate 0.5 -pattern_type glob -i 'tmp/screenshots/*.png' \
+  -c:v libx264 -pix_fmt yuv420p -vf "scale=1280:-2" \
+  tmp/videos/feature-demo.mp4
+
+# Create low-quality GIF for preview (small file, for GitHub embed)
+ffmpeg -y -framerate 0.5 -pattern_type glob -i 'tmp/screenshots/*.png' \
+  -vf "scale=640:-1:flags=lanczos,split[s0][s1];[s0]palettegen=max_colors=128[p];[s1][p]paletteuse" \
+  -loop 0 tmp/videos/feature-demo-preview.gif
+```
+
+**Note:**
+- The `-2` in MP4 scale ensures height is divisible by 2 (required for H.264)
+- Preview GIF uses 640px width and 128 colors to keep file size small (~100-200KB)
+
+## 5. Upload the Video
+
+**Upload with rclone:**
+
+```bash
+# Check rclone is configured
+rclone listremotes
+
+# Upload video, preview GIF, and screenshots to cloud storage
+# Use --s3-no-check-bucket to avoid permission errors
+rclone copy tmp/videos/ r2:your-bucket/pr-videos/pr-[number]/ --s3-no-check-bucket --progress
+rclone copy tmp/screenshots/ r2:your-bucket/pr-videos/pr-[number]/screenshots/ --s3-no-check-bucket --progress
+
+# List uploaded files
+rclone ls r2:your-bucket/pr-videos/pr-[number]/
+```
+
+## 6. Update PR Description
+
+**Get current PR body:**
+```bash
+gh pr view [number] --json body -q '.body'
+```
+
+**Add video section to PR description:**
+
+If the PR already has a video section, replace it. Otherwise, append:
+
+**IMPORTANT:** GitHub cannot embed external MP4s directly. Use a clickable GIF that links to the video:
+
+```markdown
+## Demo
+
+[![Feature Demo]([preview-gif-url])]([video-mp4-url])
+
+*Click to view full video*
+```
+
+**Update the PR:**
+```bash
+gh pr edit [number] --body "[updated body with video section]"
+```
+
+**Or add as a comment if preferred:**
+```bash
+gh pr comment [number] --body "## Feature Demo
+
+![Demo]([video-url])
+
+_Automated walkthrough of the changes in this PR_"
+```
+
+## 7. Cleanup
+
+```bash
+# Optional: Clean up screenshots
+rm -rf tmp/screenshots
+
+# Keep videos for reference
+echo "Video retained at: tmp/videos/feature-demo.gif"
+```
+
+</process>
+
+<success_criteria>
+- [ ] Video/GIF captures the complete user flow for the feature
+- [ ] PR description updated with embedded video section
+- [ ] Video uploaded to cloud storage (or local path noted)
+- [ ] All shots from the planned flow are captured
+</success_criteria>
+
+<guardrails>
+- Keep it short: 10-30 seconds is ideal for PR demos
+- Focus on the change: Don't include unrelated UI
+- Show before/after: If fixing a bug, show the broken state first (if possible)
+- Annotate if needed: Add text overlays for complex features
+</guardrails>
+
+<handoff>
+- Review the video to ensure it accurately demonstrates the feature
+- Share with reviewers for context
+- Run `/lavra-review` for a full code review of the changes
+</handoff>

package/plugins/lavra/cortex/commands/generate-command.md

@@ -0,0 +1,150 @@
+<!-- Generated by lavra-compound v0.6.0 -->
+<!-- Source: generate-command.md -->
+<!-- DO NOT EDIT - changes will be overwritten on next install -->
+
+---
+name: generate-command
+description: Create a new custom slash command following conventions and best practices
+argument-hint: [command purpose and requirements]
+disable-model-invocation: true
+---
+
+<objective>
+Create a new slash command in `.claude/commands/` for the requested task, following Claude Code command conventions and best practices.
+</objective>
+
+<execution_context>
+
+#$ARGUMENTS
+
+</execution_context>
+
+<process>
+
+## Key Capabilities to Leverage
+
+**File Operations:**
+- Read, Edit, Write - modify files precisely
+- Glob, Grep - search codebase
+- MultiEdit - atomic multi-part changes
+
+**Development:**
+- Bash - run commands (git, tests, linters)
+- Task - launch specialized agents for complex tasks
+- TaskCreate/TaskUpdate/TaskList - track progress with task lists
+
+**Web & APIs:**
+- WebFetch, WebSearch - research documentation
+- GitHub (gh cli) - PRs, issues, reviews
+- agent-browser - browser automation, screenshots
+
+**Integrations:**
+- Context7 - framework docs
+- Any MCP servers configured in the project
+
+## Best Practices
+
+1. **Be specific and clear** - detailed instructions yield better results
+2. **Break down complex tasks** - use step-by-step plans
+3. **Use examples** - reference existing code patterns
+4. **Include success criteria** - tests pass, linting clean, etc.
+5. **Think first** - use "think hard" or "plan" keywords for complex problems
+6. **Iterate** - guide the process step by step
+
+## Required: YAML Frontmatter
+
+**EVERY command MUST start with YAML frontmatter:**
+
+```yaml
+---
+name: command-name
+description: Brief description of what this command does (max 100 chars)
+argument-hint: "[what arguments the command accepts]"
+---
+```
+
+**Fields:**
+- `name`: Lowercase command identifier (used internally)
+- `description`: Clear, concise summary of command purpose
+- `argument-hint`: Shows user what arguments are expected (e.g., `[file path]`, `[PR number]`, `[optional: format]`)
+
+## Structure Your Command
+
+```markdown
+# [Command Name]
+
+[Brief description of what this command does]
+
+## Steps
+
+1. [First step with specific details]
+   - Include file paths, patterns, or constraints
+   - Reference existing code if applicable
+
+2. [Second step]
+   - Use parallel tool calls when possible
+   - Check/verify results
+
+3. [Final steps]
+   - Run tests
+   - Lint code
+   - Commit changes (if appropriate)
+
+## Success Criteria
+
+- [ ] Tests pass
+- [ ] Code follows style guide
+- [ ] Documentation updated (if needed)
+```
+
+## Tips for Effective Commands
+
+- **Use $ARGUMENTS** placeholder for dynamic inputs
+- **Reference CLAUDE.md or AGENTS.md** patterns and conventions
+- **Include verification steps** - tests, linting, visual checks
+- **Be explicit about constraints** - don't modify X, use pattern Y
+- **Use XML tags** for structured prompts: `<task>`, `<requirements>`, `<constraints>`
+
+## Example Pattern
+
+```markdown
+Implement #$ARGUMENTS following these steps:
+
+1. Research existing patterns
+   - Search for similar code using Grep
+   - Read relevant files to understand approach
+
+2. Plan the implementation
+   - Think through edge cases and requirements
+   - Consider test cases needed
+
+3. Implement
+   - Follow existing code patterns (reference specific files)
+   - Write tests first if doing TDD
+   - Ensure code follows CLAUDE.md or AGENTS.md conventions
+
+4. Verify
+   - Run tests: `bin/rails test`
+   - Run linter: `bundle exec standardrb`
+   - Check changes with git diff
+
+5. Commit (optional)
+   - Stage changes
+   - Write clear commit message
+```
+
+## Creating the Command File
+
+1. **Create the file** at `.claude/commands/[name].md` (subdirectories like `workflows/` supported)
+2. **Start with YAML frontmatter** (see section above)
+3. **Structure the command** using the template above
+4. **Test the command** by using it with appropriate arguments
+
+</process>
+
+<success_criteria>
+- Command file created at `.claude/commands/[name].md`
+- YAML frontmatter includes name, description, and argument-hint
+- Command has clear step-by-step workflow
+- Success criteria defined in the command itself
+</success_criteria>

package/plugins/lavra/cortex/commands/heal-skill.md

@@ -0,0 +1,134 @@
+<!-- Generated by lavra v0.6.0 -->
+<!-- Source: heal-skill.md -->
+<!-- DO NOT EDIT - changes will be overwritten on next install -->
+
+---
+name: heal-skill
+description: "Fix incorrect SKILL.md files when a skill has wrong instructions or outdated API references"
+argument-hint: [optional: specific issue to fix]
+allowed-tools: [Read, Edit, Bash(ls:*), Bash(git:*)]
+disable-model-invocation: true
+---
+
+<objective>
+Update a skill's SKILL.md and related files based on corrections discovered during execution. Analyze the conversation to detect which skill is running, reflect on what went wrong, propose specific fixes, get user approval, then apply changes with optional commit.
+</objective>
+
+<execution_context>
+
+$ARGUMENTS
+
+Skill detection: `ls -1 ./skills/*/SKILL.md | head -5`
+
+</execution_context>
+
+<process>
+
+## Step 1: Detect Skill
+
+Identify the skill from conversation context:
+
+- Look for skill invocation messages
+- Check which SKILL.md was recently referenced
+- Examine current task context
+
+Set: `SKILL_NAME=[skill-name]` and `SKILL_DIR=./skills/$SKILL_NAME`
+
+If unclear, ask the user.
+
+## Step 2: Reflection and Analysis
+
+Focus on $ARGUMENTS if provided, otherwise analyze broader context.
+
+Determine:
+- **What was wrong**: Quote specific sections from SKILL.md that are incorrect
+- **Discovery method**: Context7, error messages, trial and error, documentation lookup
+- **Root cause**: Outdated API, incorrect parameters, wrong endpoint, missing context
+- **Scope of impact**: Single section or multiple? Related files affected?
+- **Proposed fix**: Which files, which sections, before/after for each
+
+## Step 3: Scan Affected Files
+
+```bash
+ls -la $SKILL_DIR/
+ls -la $SKILL_DIR/references/ 2>/dev/null
+ls -la $SKILL_DIR/scripts/ 2>/dev/null
+```
+
+## Step 4: Present Proposed Changes
+
+Present changes in this format:
+
+```
+**Skill being healed:** [skill-name]
+**Issue discovered:** [1-2 sentence summary]
+**Root cause:** [brief explanation]
+
+**Files to be modified:**
+- [ ] SKILL.md
+- [ ] references/[file].md
+- [ ] scripts/[file].py
+
+**Proposed changes:**
+
+### Change 1: SKILL.md - [Section name]
+**Location:** Line [X] in SKILL.md
+
+**Current (incorrect):**
+```
+[exact text from current file]
+```
+
+**Corrected:**
+```
+[new text]
+```
+
+**Reason:** [why this fixes the issue]
+
+[repeat for each change across all files]
+
+**Impact assessment:**
+- Affects: [authentication/API endpoints/parameters/examples/etc.]
+
+**Verification:**
+These changes will prevent: [specific error that prompted this]
+```
+
+## Step 5: Request Approval
+
+```
+Should I apply these changes?
+
+1. Yes, apply and commit all changes
+2. Apply but don't commit (let me review first)
+3. Revise the changes (I'll provide feedback)
+4. Cancel (don't make changes)
+
+Choose (1-4):
+```
+
+**Wait for user response. Do not proceed without approval.**
+
+## Step 6: Apply Changes
+
+Only after approval (option 1 or 2):
+
+1. Use Edit tool for each correction across all files
+2. Read back modified sections to verify
+3. If option 1, commit with structured message showing what was healed
+4. Confirm completion with file list
+
+</process>
+
+<success_criteria>
+- Skill correctly detected from conversation context
+- All incorrect sections identified with before/after
+- User approved changes before application
+- All edits applied across SKILL.md and related files
+- Changes verified by reading back
+- Commit created if user chose option 1
+- Completion confirmed with file list
+- Cross-file consistency maintained (SKILL.md examples match references/)
+- No unintended files modified
+</success_criteria>