/feature-video

<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)

# 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:

command -v agent-browser >/dev/null 2>&1 && echo "Installed" || echo "NOT INSTALLED"

Install if needed:

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:

gh pr view [number] --json title,body,files,headRefName -q '.'

Get changed files:

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:

**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:

mkdir -p tmp/videos

Recording approach: Use browser screenshots as frames

agent-browser captures screenshots at key moments, then combine into video using ffmpeg:

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

agent-browser open "[base-url]/[start-route]"
agent-browser wait 2000
agent-browser screenshot tmp/screenshots/01-start.png

Step 2: Perform navigation/interactions

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

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

agent-browser wait 2000
agent-browser screenshot tmp/screenshots/04-result.png

Create video/GIF from screenshots:

# 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:

# 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:

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:

## Demo

[![Feature Demo]([preview-gif-url])]([video-mp4-url])

*Click to view full video*

Update the PR:

gh pr edit [number] --body "[updated body with video section]"

Or add as a comment if preferred:

gh pr comment [number] --body "## Feature Demo

![Demo]([video-url])

_Automated walkthrough of the changes in this PR_"

7. Cleanup

# 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 `/beads-review` for a full code review of the changes </handoff>