Initial commit

commands/blog-optimize-images.md

@@ -0,0 +1,381 @@
+# Blog Image Optimization
+
+Optimize article images with automated compression, format conversion (WebP), and reference updates.
+
+## Usage
+
+```bash
+/blog-optimize-images "language/article-slug"
+```
+
+**Examples**:
+```bash
+/blog-optimize-images "en/nodejs-best-practices"
+/blog-optimize-images "fr/microservices-logging"
+```
+
+**Note**: Provide the language code and article slug (path relative to `articles/`).
+
+## Prerequisites
+
+ **Required**:
+- Article exists at `articles/[language]/[slug]/article.md`
+- Images referenced in article (`.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.tiff`)
+- ffmpeg installed (for conversion)
+
+**Install ffmpeg**:
+```bash
+# macOS
+brew install ffmpeg
+
+# Windows (with Chocolatey)
+choco install ffmpeg
+
+# Windows (manual)
+# Download from: https://ffmpeg.org/download.html
+
+# Ubuntu/Debian
+sudo apt-get install ffmpeg
+```
+
+## What This Command Does
+
+Delegates to the **quality-optimizer** subagent (Phase 4) for image optimization:
+
+- **Discovers Images**: Scans article for image references
+- **Backs Up Originals**: Copies to `images/.backup/` (preserves uncompressed)
+- **Converts to WebP**: 80% quality, optimized for web
+- **Updates References**: Changes `.png` → `.webp` in article.md
+- **Reports Results**: Shows size reduction and file locations
+
+**Time**: 10-20 minutes (depends on image count/size)
+**Output**: Optimized images in `images/`, backups in `images/.backup/`
+
+## Instructions
+
+Create a new subagent conversation with the `quality-optimizer` agent.
+
+**Provide the following prompt**:
+
+```
+You are optimizing images for a blog article.
+
+**Article Path**: articles/$ARGUMENTS/article.md
+
+Execute ONLY Phase 4 (Image Optimization) from your instructions:
+
+1. **Image Discovery**:
+   - Scan article for image references
+   - Extract image paths from markdown: `grep -E '!\[.*\]\(.*\.(png|jpg|jpeg|gif|bmp|tiff)\)' article.md`
+   - Build list of images to process
+
+2. **Generate Optimization Script** (`/tmp/optimize-images-$$.sh`):
+   - Create image optimization script in /tmp/
+   - Include backup logic (copy originals to images/.backup/)
+   - Include conversion logic (to WebP, 80% quality)
+   - Include reference update logic (sed replacements in article.md)
+   - Make script executable
+
+3. **Execute Script**:
+   - Run the optimization script
+   - Capture output and errors
+   - Verify all images processed successfully
+
+4. **Validation**:
+   - Check all originals backed up to images/.backup/
+   - Verify all WebP files created in images/
+   - Confirm article.md references updated
+   - Calculate total size reduction
+
+**Important**:
+- All scripts must be in /tmp/ (never pollute project)
+- Backup originals BEFORE conversion
+- Use ffmpeg (cross-platform: Windows, macOS, Linux)
+- 80% quality for WebP conversion (hardcoded)
+- Update ALL image references in article.md
+- Report file size reductions
+
+Begin image optimization now.
+```
+
+## Expected Output
+
+After completion, verify:
+
+ **Backup Directory Created**:
+```bash
+ls articles/en/my-article/images/.backup/
+# screenshot.png (original)
+# diagram.png (original)
+```
+
+ **Optimized Images Created**:
+```bash
+ls articles/en/my-article/images/
+# screenshot.webp (optimized, 80% quality)
+# diagram.webp (optimized, 80% quality)
+```
+
+ **Article References Updated**:
+```markdown
+# Before:
+![Screenshot](images/.backup/screenshot.png)
+
+# After:
+![Screenshot](images/screenshot.webp)
+```
+
+ **Size Reduction Report**:
+```
+ Optimization Results:
+  - screenshot.png: 2.4MB → 512KB (79% reduction)
+  - diagram.png: 1.8MB → 420KB (77% reduction)
+
+  Total savings: 3.3MB (78% reduction)
+```
+
+## Supported Image Formats
+
+### Source Formats (will be converted)
+- `.png` - Portable Network Graphics
+- `.jpg` / `.jpeg` - JPEG images
+- `.gif` - Graphics Interchange Format (first frame)
+- `.bmp` - Bitmap images
+- `.tiff` - Tagged Image File Format
+
+### Target Format
+- `.webp` - WebP (80% quality, optimized)
+
+### Compression Settings
+
+**Hardcoded** (cannot be changed via command):
+- **Quality**: 80%
+- **Format**: WebP
+- **Method**: ffmpeg (cross-platform)
+
+**Why 80%?**
+- Excellent visual quality
+- Significant file size reduction (30-70%)
+- Broad browser support
+- Optimal for web performance
+
+## Image Workflow
+
+### 1. Add Images to Article
+
+Place originals in `.backup/` first:
+```bash
+cp ~/Downloads/screenshot.png articles/en/my-article/images/.backup/
+```
+
+Reference in article (use `.backup/` path initially):
+```markdown
+![Architecture Screenshot](images/.backup/screenshot.png)
+```
+
+### 2. Run Optimization
+
+```bash
+/blog-optimize-images "en/my-article"
+```
+
+### 3. Verify Results
+
+Check backups:
+```bash
+ls articles/en/my-article/images/.backup/
+# screenshot.png 
+```
+
+Check optimized:
+```bash
+ls articles/en/my-article/images/
+# screenshot.webp 
+```
+
+Check article updated:
+```bash
+grep "screenshot" articles/en/my-article/article.md
+# ![Architecture Screenshot](images/screenshot.webp) 
+```
+
+## Multi-Language Support
+
+Images are per-language/per-article:
+
+```bash
+# English article images
+/blog-optimize-images "en/my-topic"
+# → articles/en/my-topic/images/
+
+# French article images
+/blog-optimize-images "fr/my-topic"
+# → articles/fr/my-topic/images/
+```
+
+**Sharing images across languages**:
+```markdown
+# In French article, link to English image
+![Diagram](/en/my-topic/images/diagram.webp)
+```
+
+## Re-Optimization
+
+If you need to re-optimize:
+
+### Restore from Backup
+```bash
+# Copy backups back to main images/
+cp articles/en/my-article/images/.backup/* articles/en/my-article/images/
+
+# Update article references to use .backup/ again
+sed -i '' 's|images/\([^.]*\)\.webp|images/.backup/\1.png|g' articles/en/my-article/article.md
+```
+
+### Run Optimization Again
+```bash
+/blog-optimize-images "en/my-article"
+```
+
+## Troubleshooting
+
+### "ffmpeg not found"
+```bash
+# Install ffmpeg
+brew install ffmpeg                    # macOS
+choco install ffmpeg                   # Windows (Chocolatey)
+sudo apt-get install ffmpeg            # Linux
+
+# Verify installation
+ffmpeg -version
+```
+
+### "No images to optimize"
+```bash
+# Check article has image references
+grep "!\[" articles/en/my-article/article.md
+
+# Check image files exist
+ls articles/en/my-article/images/.backup/
+```
+
+### "Images not updating in article"
+```bash
+# Check current references
+grep "images/" articles/en/my-article/article.md
+
+# Manually fix if needed
+sed -i '' 's|\.png|.webp|g' articles/en/my-article/article.md
+```
+
+### "Permission denied"
+```bash
+# Make optimization script executable
+chmod +x /tmp/optimize-images-*.sh
+
+# Or run agent again (it recreates script)
+```
+
+## Performance Tips
+
+### Before Optimization
+1. **Use descriptive names**: `architecture-diagram.png` not `img1.png`
+2. **Keep high quality**: Optimization preserves visual quality
+3. **Remove unused images**: Delete unreferenced images first
+
+### After Optimization
+1. **Verify backups exist**: Check `.backup/` directory
+2. **Test image loading**: Preview article to ensure images load
+3. **Monitor file sizes**: Typical reduction 30-70%
+4. **Commit both**: Commit `.backup/` and optimized images (or just optimized)
+
+## Integration with Workflows
+
+### New Article with Images
+
+```bash
+# 1. Create article
+/blog-marketing "en/my-topic"
+
+# 2. Add images to .backup/
+cp ~/images/*.png articles/en/my-topic/images/.backup/
+
+# 3. Reference in article.md
+# ![Image](images/.backup/image.png)
+
+# 4. Optimize
+/blog-optimize-images "en/my-topic"
+
+# 5. Validate
+/blog-optimize "en/my-topic"
+```
+
+### Update Existing Article Images
+
+```bash
+# 1. Add new images to .backup/
+cp ~/new-image.png articles/en/my-topic/images/.backup/
+
+# 2. Reference in article
+# ![New Image](images/.backup/new-image.png)
+
+# 3. Re-optimize (only new images affected)
+/blog-optimize-images "en/my-topic"
+```
+
+## Storage Considerations
+
+### What to Commit to Git
+
+**Option 1: Commit Both** (recommended for collaboration)
+```gitignore
+# .gitignore - allow both
+# (images/.backup/ and images/*.webp committed)
+```
+
+**Option 2: Commit Only Optimized**
+```gitignore
+# .gitignore - exclude backups
+articles/**/images/.backup/
+```
+
+**Option 3: Commit Only Backups** (not recommended)
+```gitignore
+# .gitignore - exclude optimized
+articles/**/images/*.webp
+# (requires re-optimization on each machine)
+```
+
+### Large Images
+
+For very large originals (>10MB):
+1. Store backups externally (CDN, cloud storage)
+2. Document source URL in article frontmatter
+3. Only commit optimized `.webp` files
+
+```yaml
+---
+title: "My Article"
+image_sources:
+  - original: "https://cdn.example.com/screenshot.png"
+    optimized: "images/screenshot.webp"
+---
+```
+
+## Script Cleanup
+
+Optimization scripts are temporary:
+
+```bash
+# List optimization scripts
+ls /tmp/optimize-images-*.sh
+
+# Remove manually if needed
+rm /tmp/optimize-images-*.sh
+
+# Or let OS auto-cleanup on reboot
+```
+
+---
+
+**Ready to optimize images?** Provide the language/slug path and execute this command.