@lavralabs/lavra 0.7.0

package/plugins/lavra/commands/optional/agent-native-audit.md

@@ -0,0 +1,282 @@
+---
+name: agent-native-audit
+description: Run comprehensive agent-native architecture review with scored principles
+argument-hint: [optional: specific principle to audit]
+disable-model-invocation: true
+---
+
+<objective>
+Conduct a comprehensive review of the codebase against agent-native architecture principles, launching parallel sub-agents for each principle and producing a scored report.
+</objective>
+
+<execution_context>
+
+If $ARGUMENTS specifies a single principle (e.g., "action parity"), only run that sub-agent and provide detailed findings for that principle alone.
+
+Valid arguments:
+- `action parity` or `1`
+- `tools` or `primitives` or `2`
+- `context` or `injection` or `3`
+- `shared` or `workspace` or `4`
+- `crud` or `5`
+- `ui` or `integration` or `6`
+- `discovery` or `7`
+- `prompt` or `features` or `8`
+
+</execution_context>
+
+<context>
+
+## Core Principles to Audit
+
+1. **Action Parity** - "Whatever the user can do, the agent can do"
+2. **Tools as Primitives** - "Tools provide capability, not behavior"
+3. **Context Injection** - "System prompt includes dynamic context about app state"
+4. **Shared Workspace** - "Agent and user work in the same data space"
+5. **CRUD Completeness** - "Every entity has full CRUD (Create, Read, Update, Delete)"
+6. **UI Integration** - "Agent actions immediately reflected in UI"
+7. **Capability Discovery** - "Users can discover what the agent can do"
+8. **Prompt-Native Features** - "Features are prompts defining outcomes, not code"
+
+</context>
+
+<process>
+
+## Step 1: Load the Agent-Native Skill
+
+First, invoke the agent-native-architecture skill to understand all principles:
+
+```
+/agent-native-architecture
+```
+
+Select option 7 (action parity) to load the full reference material.
+
+## Step 2: Launch Parallel Sub-Agents
+
+Launch 8 parallel sub-agents using the Task tool with `subagent_type: Explore`, one for each principle. Each agent should:
+
+1. Enumerate ALL instances in the codebase (user actions, tools, contexts, data stores, etc.)
+2. Check compliance against the principle
+3. Provide a SPECIFIC SCORE like "X out of Y (percentage%)"
+4. List specific gaps and recommendations
+
+**Agent 1: Action Parity**
+```
+Audit for ACTION PARITY - "Whatever the user can do, the agent can do."
+
+Tasks:
+1. Enumerate ALL user actions in frontend (API calls, button clicks, form submissions)
+   - Search for API service files, fetch calls, form handlers
+   - Check routes and components for user interactions
+2. Check which have corresponding agent tools
+   - Search for agent tool definitions
+   - Map user actions to agent capabilities
+3. Score: "Agent can do X out of Y user actions"
+
+Format:
+## Action Parity Audit
+### User Actions Found
+| Action | Location | Agent Tool | Status |
+### Score: X/Y (percentage%)
+### Missing Agent Tools
+### Recommendations
+```
+
+**Agent 2: Tools as Primitives**
+```
+Audit for TOOLS AS PRIMITIVES - "Tools provide capability, not behavior."
+
+Tasks:
+1. Find and read ALL agent tool files
+2. Classify each as:
+   - PRIMITIVE (good): read, write, store, list - enables capability without business logic
+   - WORKFLOW (bad): encodes business logic, makes decisions, orchestrates steps
+3. Score: "X out of Y tools are proper primitives"
+
+Format:
+## Tools as Primitives Audit
+### Tool Analysis
+| Tool | File | Type | Reasoning |
+### Score: X/Y (percentage%)
+### Problematic Tools (workflows that should be primitives)
+### Recommendations
+```
+
+**Agent 3: Context Injection**
+```
+Audit for CONTEXT INJECTION - "System prompt includes dynamic context about app state"
+
+Tasks:
+1. Find context injection code (search for "context", "system prompt", "inject")
+2. Read agent prompts and system messages
+3. Enumerate what IS injected vs what SHOULD be:
+   - Available resources (files, drafts, documents)
+   - User preferences/settings
+   - Recent activity
+   - Available capabilities listed
+   - Session history
+   - Workspace state
+
+Format:
+## Context Injection Audit
+### Context Types Analysis
+| Context Type | Injected? | Location | Notes |
+### Score: X/Y (percentage%)
+### Missing Context
+### Recommendations
+```
+
+**Agent 4: Shared Workspace**
+```
+Audit for SHARED WORKSPACE - "Agent and user work in the same data space"
+
+Tasks:
+1. Identify all data stores/tables/models
+2. Check if agents read/write to SAME tables or separate ones
+3. Look for sandbox isolation anti-pattern (agent has separate data space)
+
+Format:
+## Shared Workspace Audit
+### Data Store Analysis
+| Data Store | User Access | Agent Access | Shared? |
+### Score: X/Y (percentage%)
+### Isolated Data (anti-pattern)
+### Recommendations
+```
+
+**Agent 5: CRUD Completeness**
+```
+Audit for CRUD COMPLETENESS - "Every entity has full CRUD"
+
+Tasks:
+1. Identify all entities/models in the codebase
+2. For each entity, check if agent tools exist for:
+   - Create
+   - Read
+   - Update
+   - Delete
+3. Score per entity and overall
+
+Format:
+## CRUD Completeness Audit
+### Entity CRUD Analysis
+| Entity | Create | Read | Update | Delete | Score |
+### Overall Score: X/Y entities with full CRUD (percentage%)
+### Incomplete Entities (list missing operations)
+### Recommendations
+```
+
+**Agent 6: UI Integration**
+```
+Audit for UI INTEGRATION - "Agent actions immediately reflected in UI"
+
+Tasks:
+1. Check how agent writes/changes propagate to frontend
+2. Look for:
+   - Streaming updates (SSE, WebSocket)
+   - Polling mechanisms
+   - Shared state/services
+   - Event buses
+   - File watching
+3. Identify "silent actions" anti-pattern (agent changes state but UI doesn't update)
+
+Format:
+## UI Integration Audit
+### Agent Action -> UI Update Analysis
+| Agent Action | UI Mechanism | Immediate? | Notes |
+### Score: X/Y (percentage%)
+### Silent Actions (anti-pattern)
+### Recommendations
+```
+
+**Agent 7: Capability Discovery**
+```
+Audit for CAPABILITY DISCOVERY - "Users can discover what the agent can do"
+
+Tasks:
+1. Check for these 7 discovery mechanisms:
+   - Onboarding flow showing agent capabilities
+   - Help documentation
+   - Capability hints in UI
+   - Agent self-describes in responses
+   - Suggested prompts/actions
+   - Empty state guidance
+   - Slash commands (/help, /tools)
+2. Score against 7 mechanisms
+
+Format:
+## Capability Discovery Audit
+### Discovery Mechanism Analysis
+| Mechanism | Exists? | Location | Quality |
+### Score: X/7 (percentage%)
+### Missing Discovery
+### Recommendations
+```
+
+**Agent 8: Prompt-Native Features**
+```
+Audit for PROMPT-NATIVE FEATURES - "Features are prompts defining outcomes, not code"
+
+Tasks:
+1. Read all agent prompts
+2. Classify each feature/behavior as defined in:
+   - PROMPT (good): outcomes defined in natural language
+   - CODE (bad): business logic hardcoded
+3. Check if behavior changes require prompt edit vs code change
+
+Format:
+## Prompt-Native Features Audit
+### Feature Definition Analysis
+| Feature | Defined In | Type | Notes |
+### Score: X/Y (percentage%)
+### Code-Defined Features (anti-pattern)
+### Recommendations
+```
+
+## Step 3: Compile Summary Report
+
+After all agents complete, compile a summary with:
+
+```markdown
+## Agent-Native Architecture Review: [Project Name]
+
+### Overall Score Summary
+
+| Core Principle | Score | Percentage | Status |
+|----------------|-------|------------|--------|
+| Action Parity | X/Y | Z% | Pass/Warn/Fail |
+| Tools as Primitives | X/Y | Z% | Pass/Warn/Fail |
+| Context Injection | X/Y | Z% | Pass/Warn/Fail |
+| Shared Workspace | X/Y | Z% | Pass/Warn/Fail |
+| CRUD Completeness | X/Y | Z% | Pass/Warn/Fail |
+| UI Integration | X/Y | Z% | Pass/Warn/Fail |
+| Capability Discovery | X/Y | Z% | Pass/Warn/Fail |
+| Prompt-Native Features | X/Y | Z% | Pass/Warn/Fail |
+
+**Overall Agent-Native Score: X%**
+
+### Status Legend
+- Pass: Excellent (80%+)
+- Warn: Partial (50-79%)
+- Fail: Needs Work (<50%)
+
+### Top 10 Recommendations by Impact
+
+| Priority | Action | Principle | Effort |
+|----------|--------|-----------|--------|
+
+### What's Working Excellently
+
+[List top 5 strengths]
+```
+
+</process>
+
+<success_criteria>
+- [ ] All 8 sub-agents complete their audits
+- [ ] Each principle has a specific numeric score (X/Y format)
+- [ ] Summary table shows all scores and status indicators
+- [ ] Top 10 recommendations are prioritized by impact
+- [ ] Report identifies both strengths and gaps
+</success_criteria>

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

@@ -0,0 +1,262 @@
+---
+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/commands/optional/generate-command.md

@@ -0,0 +1,146 @@
+---
+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>