@every-env/compound-plugin 0.1.0

package/plugins/compound-engineering/commands/feature-video.md

@@ -0,0 +1,342 @@
+---
+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]"
+---
+
+# Feature Video Walkthrough
+
+<command_purpose>Record a video walkthrough demonstrating a feature, upload it, and add it to the PR description.</command_purpose>
+
+## Introduction
+
+<role>Developer Relations Engineer creating feature demo videos</role>
+
+This command creates professional video walkthroughs of features for PR documentation:
+- Records browser interactions using agent-browser CLI
+- Demonstrates the complete user flow
+- Uploads the video for easy sharing
+- Updates the PR description with an embedded video
+
+## Prerequisites
+
+<requirements>
+- 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)
+</requirements>
+
+## 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.
+
+## Main Tasks
+
+### 1. Parse Arguments
+
+<parse_args>
+
+**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'
+```
+
+</parse_args>
+
+### 2. Gather Feature Context
+
+<gather_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** (same as playwright-test):
+
+| 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 |
+
+</gather_context>
+
+### 3. Plan the Video Flow
+
+<plan_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
+```
+
+</plan_flow>
+
+### 4. Setup Video Recording
+
+<setup_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
+```
+
+</setup_recording>
+
+### 5. Record the Walkthrough
+
+<record_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)
+
+</record_walkthrough>
+
+### 6. Upload the Video
+
+<upload_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:kieran-claude/pr-videos/pr-[number]/ --s3-no-check-bucket --progress
+rclone copy tmp/screenshots/ r2:kieran-claude/pr-videos/pr-[number]/screenshots/ --s3-no-check-bucket --progress
+
+# List uploaded files
+rclone ls r2:kieran-claude/pr-videos/pr-[number]/
+```
+
+Public URLs (R2 with public access):
+```
+Video: https://pub-4047722ebb1b4b09853f24d3b61467f1.r2.dev/pr-videos/pr-[number]/feature-demo.mp4
+Preview: https://pub-4047722ebb1b4b09853f24d3b61467f1.r2.dev/pr-videos/pr-[number]/feature-demo-preview.gif
+```
+
+</upload_video>
+
+### 7. Update PR Description
+
+<update_pr>
+
+**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*
+```
+
+Example:
+```markdown
+[![Feature Demo](https://pub-4047722ebb1b4b09853f24d3b61467f1.r2.dev/pr-videos/pr-137/feature-demo-preview.gif)](https://pub-4047722ebb1b4b09853f24d3b61467f1.r2.dev/pr-videos/pr-137/feature-demo.mp4)
+```
+
+**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_"
+```
+
+</update_pr>
+
+### 8. Cleanup
+
+<cleanup>
+
+```bash
+# Optional: Clean up screenshots
+rm -rf tmp/screenshots
+
+# Keep videos for reference
+echo "Video retained at: tmp/videos/feature-demo.gif"
+```
+
+</cleanup>
+
+### 9. Summary
+
+<summary>
+
+Present completion summary:
+
+```markdown
+## Feature Video Complete
+
+**PR:** #[number] - [title]
+**Video:** [url or local path]
+**Duration:** ~[X] seconds
+**Format:** [GIF/MP4]
+
+### Shots Captured
+1. [Starting point] - [description]
+2. [Navigation] - [description]
+3. [Feature demo] - [description]
+4. [Result] - [description]
+
+### PR Updated
+- [x] Video section added to PR description
+- [ ] Ready for review
+
+**Next steps:**
+- Review the video to ensure it accurately demonstrates the feature
+- Share with reviewers for context
+```
+
+</summary>
+
+## Quick Usage Examples
+
+```bash
+# Record video for current branch's PR
+/feature-video
+
+# Record video for specific PR
+/feature-video 847
+
+# Record with custom base URL
+/feature-video 847 http://localhost:5000
+
+# Record for staging environment
+/feature-video current https://staging.example.com
+```
+
+## Tips
+
+- **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

package/plugins/compound-engineering/commands/generate_command.md

@@ -0,0 +1,162 @@
+---
+name: generate_command
+description: Create a new custom slash command following conventions and best practices
+argument-hint: "[command purpose and requirements]"
+---
+
+# Create a Custom Claude Code Command
+
+Create a new slash command in `.claude/commands/` for the requested task.
+
+## Goal
+
+#$ARGUMENTS
+
+## 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
+- TodoWrite - track progress with todo lists
+
+**Web & APIs:**
+- WebFetch, WebSearch - research documentation
+- GitHub (gh cli) - PRs, issues, reviews
+- Playwright - browser automation, screenshots
+
+**Integrations:**
+- AppSignal - logs and monitoring
+- Context7 - framework docs
+- Stripe, Todoist, Featurebase (if relevant)
+
+## 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** 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 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
+
+## Command File Template
+
+```markdown
+---
+name: command-name
+description: What this command does
+argument-hint: "[expected arguments]"
+---
+
+# Command Title
+
+Brief introduction of what the command does and when to use it.
+
+## Workflow
+
+### Step 1: [First Major Step]
+
+Details about what to do.
+
+### Step 2: [Second Major Step]
+
+Details about what to do.
+
+## Success Criteria
+
+- [ ] Expected outcome 1
+- [ ] Expected outcome 2
+```

package/plugins/compound-engineering/commands/heal-skill.md

@@ -0,0 +1,142 @@
+---
+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:*)]
+---
+
+<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>
+
+<context>
+Skill detection: !`ls -1 ./skills/*/SKILL.md | head -5`
+</context>
+
+<quick_start>
+<workflow>
+1. **Detect skill** from conversation context (invocation messages, recent SKILL.md references)
+2. **Reflect** on what went wrong and how you discovered the fix
+3. **Present** proposed changes with before/after diffs
+4. **Get approval** before making any edits
+5. **Apply** changes and optionally commit
+</workflow>
+</quick_start>
+
+<process>
+<step_1 name="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_1>
+
+<step_2 name="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_2>
+
+<step_3 name="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_3>
+
+<step_4 name="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_4>
+
+<step_5 name="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_5>
+
+<step_6 name="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
+</step_6>
+</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
+</success_criteria>
+
+<verification>
+Before completing:
+
+- Read back each modified section to confirm changes applied
+- Ensure cross-file consistency (SKILL.md examples match references/)
+- Verify git commit created if option 1 was selected
+- Check no unintended files were modified
+</verification>

package/plugins/compound-engineering/commands/lfg.md

@@ -0,0 +1,19 @@
+---
+name: lfg
+description: Full autonomous engineering workflow
+argument-hint: "[feature description]"
+---
+
+Run these slash commands in order. Do not do anything else.
+
+1. `/ralph-wiggum:ralph-loop "finish all slash commands" --completion-promise "DONE"`
+2. `/workflows:plan $ARGUMENTS`
+3. `/compound-engineering:deepen-plan`
+4. `/workflows:work`
+5. `/workflows:review`
+6. `/compound-engineering:resolve_todo_parallel`
+7. `/compound-engineering:test-browser`
+8. `/compound-engineering:feature-video`
+9. Output `<promise>DONE</promise>` when video is in PR
+
+Start with step 1 now.

package/plugins/compound-engineering/commands/plan_review.md

@@ -0,0 +1,7 @@
+---
+name: plan_review
+description: Have multiple specialized agents review a plan in parallel
+argument-hint: "[plan file path or plan content]"
+---
+
+Have @agent-dhh-rails-reviewer @agent-kieran-rails-reviewer @agent-code-simplicity-reviewer review this plan in parallel.