luna-agents 2.0.1

package/commands/ll-vision-pipeline.md

@@ -0,0 +1,247 @@
+---
+name: ll-vision-pipeline
+displayName: Luna Vision Pipeline
+description: Master orchestrator — chains browser-test → visual-qa → visual-diff → a11y-scan → auto-fix loop across all vision MCP servers
+version: 1.0.0
+category: testing
+agent: luna-vision-pipeline
+parameters:
+  - name: url
+    type: string
+    description: App URL to test (e.g., http://localhost:3000)
+    required: true
+    prompt: true
+  - name: baseline
+    type: string
+    description: Path to baseline screenshots for regression diff (or "none" to skip diff layer)
+    required: false
+    default: none
+  - name: fix
+    type: boolean
+    description: "Enable auto-fix loop (default: true)"
+    required: false
+    default: true
+  - name: max_fix_rounds
+    type: number
+    description: "Max auto-fix retry rounds (default: 3)"
+    required: false
+    default: 3
+workflow:
+  - detect_and_launch
+  - capture_all_screenshots
+  - parallel_analysis
+  - correlate_findings
+  - auto_fix_loop
+  - retest_and_verify
+  - generate_master_report
+output:
+  - .luna/{current-project}/vision-pipeline/
+  - .luna/{current-project}/vision-pipeline/report.md
+prerequisites: []
+mcp_servers:
+  - zai-mcp-server
+  - image-compare
+  - accessibility-scanner
+  - image-extractor
+  - playwright
+  - puppeteer
+  - fetch
+  - ruflo
+---
+
+# Luna Vision Pipeline — Master Orchestrator
+
+The ultimate visual QA command. Chains **all vision MCP servers** in a single pipeline with auto-fix loop.
+
+## Full Pipeline
+
+```
+/vision-pipeline http://localhost:3000
+          │
+          ▼
+┌─────────────────────────────────────────────────────────────┐
+│  PHASE 1: CAPTURE                                           │
+│  Playwright: detect routes → screenshot all pages            │
+│  Output: 4 viewports × N pages = screenshots/               │
+└──────────────────────────┬──────────────────────────────────┘
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│  PHASE 2: PARALLEL ANALYSIS (all run simultaneously)         │
+│                                                              │
+│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐         │
+│  │ zai-mcp      │ │ image-compare│ │ a11y-scanner │         │
+│  │ Vision AI    │ │ Pixel Diff   │ │ WCAG axe-core│         │
+│  │              │ │              │ │              │         │
+│  │ • Layout     │ │ • vs baseline│ │ • Contrast   │         │
+│  │ • Content    │ │ • Diff %     │ │ • ARIA       │         │
+│  │ • Style      │ │ • Overlay    │ │ • Keyboard   │         │
+│  │ • HIG        │ │ • Regression │ │ • Labels     │         │
+│  │ • Brand      │ │   detection  │ │ • Headings   │         │
+│  └──────┬───────┘ └──────┬───────┘ └──────┬───────┘         │
+│         │                │                │                  │
+│  ┌──────────────┐                                           │
+│  │ image-extract│  (feeds screenshots into Claude Vision)    │
+│  │ • OCR/text   │                                           │
+│  │ • Typos      │                                           │
+│  │ • Placeholders│                                          │
+│  └──────┬───────┘                                           │
+└─────────┼────────────────┼────────────────┼─────────────────┘
+          │                │                │
+          └────────────────┼────────────────┘
+                           ▼
+���─────────────────────────────────────────────────────────────┐
+│  PHASE 3: CORRELATE                                          │
+│  Cross-reference findings from all 4 analysis layers         │
+│  Deduplicate (same issue found by multiple layers)           │
+│  Prioritize by combined severity score                       │
+│  Map each finding to source file + component                 │
+└──────────────────────────┬──────────────────────────────────┘
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│  PHASE 4: AUTO-FIX LOOP (if enabled)                         │
+│                                                              │
+│  For each CRITICAL/HIGH finding:                             │
+│    1. Read source component                                  │
+│    2. Generate fix (max 100 lines)                           │
+│    3. Apply fix                                              │
+│    4. Re-capture screenshot                                  │
+│    5. Re-analyze with same MCP layer                         │
+│    6. If fixed → next issue                                  │
+│    7. If not fixed → retry (max 3)                           │
+│    8. If still broken → log as blocker                       │
+│                                                              │
+│  After all fixes:                                            │
+│    Re-run FULL pipeline to verify no regressions             │
+└──────────────────────────┬──────────────────────────────────┘
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│  PHASE 5: MASTER REPORT                                      │
+│                                                              │
+│  report.md — unified findings from all layers                │
+│  ├── Executive summary (pass/fail, score /100)               │
+│  ├── Per-page breakdown                                      │
+│  │   ├── Vision AI findings                                  │
+│  │   ├── Regression diff (if baseline provided)              │
+│  │   ├── Accessibility violations                            │
+│  │   └── OCR text issues                                     │
+│  ├── Fixes applied (before/after)                            │
+│  ├── Remaining blockers                                      │
+│  └── Screenshot gallery                                      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Usage
+
+```bash
+# Full pipeline — all layers, auto-fix enabled
+/vision-pipeline http://localhost:3000
+
+# With regression baseline
+/vision-pipeline http://localhost:3000 --baseline .luna/baselines/
+
+# Analysis only, no auto-fix
+/vision-pipeline http://localhost:3000 --fix false
+
+# Limit fix rounds
+/vision-pipeline http://localhost:3000 --max-fix-rounds 1
+```
+
+## In Pipes
+
+```bash
+# The ultimate pre-release check
+/pipe vision-pipeline http://localhost:3000 --baseline .luna/baselines/ ?>> ship !>> "Visual QA failed"
+
+# Dev loop: code → full visual QA → fix → ship
+/pipe go *5 >> vision-pipeline http://localhost:3000 ?>> pr !>> (fix >> vision-pipeline) *2?
+
+# Save baseline after successful QA
+/pipe vision-pipeline http://localhost:3000 ?>> visual-diff save >> ship
+
+# Compare environments
+/pipe vision-pipeline https://staging.app.com --baseline ./prod-screenshots >> approve >> deploy
+```
+
+## Scoring
+
+The pipeline produces a Visual QA Score (0-100):
+
+| Component | Weight | What It Measures |
+|-----------|--------|-----------------|
+| Vision AI | 30% | Layout, content, style, HIG compliance |
+| Regression | 20% | Pixel stability vs baseline |
+| Accessibility | 30% | WCAG 2.1 AA compliance |
+| Performance | 10% | Load times, Core Web Vitals |
+| Text/OCR | 10% | Correct copy, no placeholders, no typos |
+
+**Pass threshold**: >= 80/100 (configurable)
+
+## Output
+
+```
+.luna/{project}/vision-pipeline/
+  report.md                 # Master unified report
+  score.json                # Visual QA score breakdown
+  screenshots/              # All captured screenshots
+  vision/                   # zai-mcp-server findings
+  diffs/                    # image-compare overlays
+  accessibility/            # axe-core results
+  ocr/                      # Extracted text
+  performance/              # Load time metrics
+  correlation/              # Cross-layer unified findings
+  fixes/                    # Applied fix diffs
+    before/                 # Pre-fix screenshots
+    after/                  # Post-fix screenshots
+    {component}.diff
+```
+
+## MCP Server Orchestration
+
+This command demonstrates Luna's multi-MCP architecture:
+
+| Server | Role | Runs In |
+|--------|------|---------|
+| **playwright** (Anthropic) | Browser automation + screenshot capture | Phase 1 |
+| **puppeteer** (MCP official) | Fallback browser automation + headless screenshots | Phase 1 |
+| **zai-mcp-server** | AI vision analysis, UI-to-code, error diagnosis | Phase 2 (parallel) |
+| **image-compare** | Pixel-perfect regression diff (Pixelmatch) | Phase 2 (parallel) |
+| **accessibility-scanner** | WCAG 2.1 axe-core compliance | Phase 2 (parallel) |
+| **image-extractor** | Feed screenshots to Claude Vision for OCR | Phase 2 (parallel) |
+| **fetch** (MCP official) | Validate live URLs, fetch page content for text comparison | Phase 2 (parallel) |
+| **ruflo** | Multi-agent swarm for parallel page analysis (313 tools) | Phase 2 (orchestration) |
+| **git** (MCP official) | Diff analysis, identify changed components for targeted testing | Phase 0 (pre-capture) |
+| **memory** (MCP official) | Persist findings across sessions, track regressions over time | Phase 5 (post-report) |
+| **Claude** (orchestrator) | Correlate, auto-fix, report | Phase 3-5 |
+
+**11 MCP servers** working as one. Each is a specialist. Together they see what no single tool can see alone.
+
+## Ruflo Integration
+
+When ruflo is enabled, Phase 2 upgrades from sequential analysis to **swarm coordination**:
+
+```
+ruflo swarm_init → spawn specialist agents
+  ├── vision-agent (uses zai-mcp tools)
+  ├── diff-agent (uses image-compare tools)
+  ├── a11y-agent (uses accessibility-scanner tools)
+  ├── content-agent (uses fetch + image-extractor tools)
+  └── perf-agent (uses playwright metrics)
+
+All agents analyze in parallel with consensus protocol
+Results merged via ruflo's semantic routing
+```
+
+## Git-Aware Smart Testing
+
+When git MCP is available, Phase 0 runs before capture:
+
+```
+git diff main...HEAD → identify changed files
+  ├── Changed components → test those pages first
+  ├── Changed styles → full visual regression
+  ├── Changed routes → re-detect route map
+  └── No changes → skip to baseline comparison
+```

package/commands/ll-vision.md

@@ -0,0 +1,74 @@
+---
+name: ll-vision
+displayName: Luna Vision AI
+description: Screenshot-to-code and UI analysis — analyze designs, compare implementations, detect regressions
+version: 1.0.0
+category: ai
+agent: luna-glm-vision
+parameters:
+  - name: action
+    type: string
+    description: Action (screenshot-to-code, compare, analyze, diff, audit)
+    required: true
+    prompt: true
+  - name: target
+    type: string
+    description: Screenshot path, URL, or component path
+    required: true
+    prompt: true
+workflow:
+  - capture_or_load_screenshot
+  - analyze_visual_content
+  - generate_code_or_report
+  - validate_output
+  - generate_vision_report
+output:
+  - .luna/{current-project}/vision-report.md
+prerequisites: []
+---
+
+# Luna Vision AI
+
+Visual AI that understands screenshots, designs, and UI implementations.
+
+## What This Command Does
+
+Uses GLM Vision + Nexa RAG to analyze visual content and generate or validate code.
+
+## Actions
+
+| Action | What It Does |
+|--------|-------------|
+| `screenshot-to-code` | Convert a screenshot/design into React components |
+| `compare` | Compare design mockup vs actual implementation |
+| `analyze` | Describe what a UI screenshot contains |
+| `diff` | Visual diff between two screenshots (before/after) |
+| `audit` | Check UI against Apple HIG and brand guidelines |
+
+## Usage
+
+```
+/vision screenshot-to-code ./designs/dashboard.png
+/vision compare ./designs/login.png http://localhost:3000/login
+/vision analyze ./screenshots/error-state.png
+/vision diff ./before.png ./after.png
+/vision audit http://localhost:3000/dashboard
+```
+
+## Architecture
+
+```
+Screenshot/Design image
+  -> GLM Vision: extract UI structure and content
+  -> Nexa RAG: match against existing component patterns
+  -> Code Generator: produce React/Tailwind components
+  -> Validator: check against brand + HIG rules
+```
+
+## Features
+
+- Figma screenshot to React + Tailwind code
+- Visual regression detection between deployments
+- Accessibility issues visible in screenshots (contrast, sizing)
+- Brand consistency checking (colors, fonts, spacing)
+- Mobile vs desktop layout comparison

package/commands/ll-visual-diff.md

@@ -0,0 +1,118 @@
+---
+name: ll-visual-diff
+displayName: Luna Visual Diff
+description: Pixel-perfect visual regression testing — compare screenshots against baseline using MCP image-compare server
+version: 1.0.0
+category: testing
+agent: luna-visual-diff
+parameters:
+  - name: url
+    type: string
+    description: App URL to capture current screenshots from
+    required: true
+    prompt: true
+  - name: baseline
+    type: string
+    description: Path to baseline screenshots directory (or "save" to create new baseline)
+    required: true
+    prompt: true
+  - name: threshold
+    type: number
+    description: "Pixel diff threshold percentage to flag as regression (default: 5)"
+    required: false
+    default: 5
+workflow:
+  - capture_current_screenshots
+  - load_baseline_screenshots
+  - run_pixel_diff_comparison
+  - generate_diff_overlays
+  - classify_regressions
+  - generate_diff_report
+output:
+  - .luna/{current-project}/visual-diff/
+  - .luna/{current-project}/visual-diff/report.md
+prerequisites: []
+mcp_servers:
+  - image-compare
+---
+
+# Luna Visual Diff — Pixel-Perfect Regression Testing
+
+Compare your app's current state against a known-good baseline. Uses the **image-compare MCP server** (Pixelmatch algorithm) for deterministic, AI-free pixel comparison.
+
+## How It Works
+
+```
+Baseline screenshots          Current screenshots
+(saved from last release)     (captured now from live app)
+        │                              │
+        └──────────┬───────────────────┘
+                   ▼
+        ┌─────────────────────┐
+        │   image-compare MCP  │
+        │   Pixelmatch engine  │
+        │   Anti-alias aware   │
+        └──────────┬──────────┘
+                   ▼
+        ┌─────────────────────┐
+        │   Diff overlay PNGs  │
+        │   Changed pixels RED │
+        │   Diff % per page    │
+        └──────────┬──────────┘
+                   ▼
+        ┌─────────────────────┐
+        │  Regression Report   │
+        │  Pass/Fail per page  │
+        │  Visual diff gallery │
+        └─────────────────────┘
+```
+
+## Usage
+
+```bash
+# Save current state as baseline
+/visual-diff http://localhost:3000 save
+
+# Compare against saved baseline
+/visual-diff http://localhost:3000 .luna/baselines/
+
+# Compare with custom threshold (10% = more lenient)
+/visual-diff http://localhost:3000 .luna/baselines/ --threshold 10
+
+# Compare staging vs production
+/visual-diff https://staging.app.com ./prod-screenshots/
+```
+
+## In Pipes
+
+```bash
+# Save baseline → make changes → diff
+/pipe visual-diff http://localhost:3000 save >> go *5 >> visual-diff http://localhost:3000 .luna/baselines/ >> assert "0 regressions"
+
+# Pre-PR regression check
+/pipe visual-diff http://localhost:3000 .luna/baselines/ ?>> pr !>> fix
+
+# Full pipeline: test → diff → a11y → ship
+/pipe browser-test http://localhost:3000 >> visual-diff http://localhost:3000 .luna/baselines/ >> visual-qa a11y >> pr
+```
+
+## Output
+
+```
+.luna/{project}/visual-diff/
+  report.md              # Regression report with pass/fail
+  baselines/             # Saved baseline screenshots (when using "save")
+  current/               # Current captured screenshots
+  diffs/                 # Diff overlay images
+    {page}-{viewport}-diff.png
+  stats.json             # Per-page diff percentages
+```
+
+## Threshold Guide
+
+| Threshold | Use Case |
+|-----------|----------|
+| 1% | Strict — catch any rendering change |
+| 5% | Default — catch layout regressions, ignore anti-aliasing |
+| 10% | Lenient — catch major layout breaks only |
+| 20% | Very lenient — only flag completely broken pages |

package/commands/ll-visual-qa.md

@@ -0,0 +1,204 @@
+---
+name: ll-visual-qa
+displayName: Luna Visual QA
+description: Multi-layer visual quality assurance — combines vision AI, pixel diff, accessibility scanning, and OCR across all MCP servers
+version: 1.0.0
+category: testing
+agent: luna-visual-qa
+parameters:
+  - name: url
+    type: string
+    description: App URL to test (e.g., http://localhost:3000)
+    required: true
+    prompt: true
+  - name: mode
+    type: string
+    description: "Mode: full (all layers), vision (AI analysis), diff (pixel compare), a11y (accessibility), ocr (text extraction)"
+    required: false
+    prompt: true
+    default: full
+  - name: baseline
+    type: string
+    description: Path to baseline screenshots for regression diff (optional)
+    required: false
+workflow:
+  - capture_screenshots
+  - run_vision_analysis
+  - run_pixel_diff
+  - run_accessibility_scan
+  - run_ocr_extraction
+  - correlate_findings
+  - generate_visual_qa_report
+output:
+  - .luna/{current-project}/visual-qa/
+  - .luna/{current-project}/visual-qa/report.md
+prerequisites: []
+mcp_servers:
+  - zai-mcp-server
+  - image-compare
+  - accessibility-scanner
+  - image-extractor
+---
+
+# Luna Visual QA — Multi-Layer MCP Pipeline
+
+The most powerful visual quality assurance command in Luna. Orchestrates **5 MCP servers** in a layered pipeline where each server handles one specialized job, and findings are correlated across layers for maximum coverage.
+
+## Architecture
+
+```
+                    ┌─────────────────────────────────┐
+                    │     /visual-qa <url> [mode]      │
+                    └──────────────┬──────────────────┘
+                                   │
+                    ┌──────────────▼──────────────────┐
+                    │   Layer 0: CAPTURE               │
+                    │   Playwright screenshots          │
+                    │   4 viewports × all routes        │
+                    └──────────────┬──────────────────┘
+                                   │
+           ┌───────────┬───────────┼───────────┬───────────┐
+           ▼           ▼           ▼           ▼           ▼
+    ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
+    │ Layer 1 │ │ Layer 2 │ │ Layer 3 │ │ Layer 4 │ │ Layer 5 │
+    │ VISION  │ │  DIFF   │ │  A11Y   │ │   OCR   │ │  PERF   │
+    │ zai-mcp │ │ img-cmp │ │ axe-core│ │ extract │ │ Playwrt │
+    └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘
+         │           │           │           │           │
+         └───────────┴───────────┼───────────┴───────────┘
+                                 ▼
+                    ┌──────────────────────────────────┐
+                    │   Layer 6: CORRELATE              │
+                    │   Cross-reference all findings    │
+                    │   Deduplicate & prioritize        │
+                    │   Generate unified report         │
+                    └──────────────────────────────────┘
+```
+
+## What Each Layer Does
+
+### Layer 0: Capture (Playwright)
+- Navigate every route in the app
+- Screenshot at 4 viewports: mobile (375px), tablet (768px), laptop (1024px), desktop (1440px)
+- Capture both light and dark mode (if supported)
+- Record page load times, network requests, console errors
+
+### Layer 1: Vision AI Analysis (zai-mcp-server)
+**MCP tools used**: `analyze_image`, `ui_diff_check`, `diagnose_error_screenshot`, `ui_to_artifact`
+- AI-powered layout analysis (overlapping, broken grids, overflow)
+- Missing content detection (empty containers, broken images)
+- Style consistency check (colors, spacing, fonts, brand)
+- Apple HIG compliance scoring
+- Dark mode correctness
+- Responsive behavior assessment
+- Generates fix suggestions with code snippets
+
+### Layer 2: Pixel Diff Regression (image-compare MCP)
+**MCP tools used**: `compare_images`, `capture_and_compare`
+- Compare current screenshots against baseline (previous release)
+- Pixel-level diff using Pixelmatch algorithm
+- Anti-aliasing aware comparison
+- Generates visual diff overlay images (red = changed pixels)
+- Reports diff percentage per page per viewport
+- Flags pages that changed more than threshold (default: 5%)
+
+### Layer 3: Accessibility Scan (accessibility-scanner MCP)
+**MCP tools used**: `run_accessibility_scan`, `get_scan_results`
+- Full WCAG 2.1 AA compliance check
+- Color contrast ratio validation
+- Missing alt text, ARIA labels, roles
+- Keyboard navigation issues
+- Focus indicator visibility
+- Touch target sizes (mobile)
+- Form label associations
+- Heading hierarchy validation
+
+### Layer 4: OCR Text Extraction (image-extractor MCP → Claude Vision)
+**MCP tools used**: `extract_image_from_file`
+- Extract all visible text from screenshots
+- Detect typos, wrong brand names, placeholder text
+- Verify text content matches expected copy
+- Check for truncated text at mobile viewports
+- Validate that no debug/dev text appears in production
+
+### Layer 5: Performance Metrics (Playwright)
+- Page load time (domcontentloaded, networkidle)
+- Largest Contentful Paint (LCP)
+- Cumulative Layout Shift (CLS)
+- Total Blocking Time (TBT)
+- Console errors/warnings count
+- Failed network requests
+
+## Cross-Layer Correlation
+
+The correlation engine combines findings from all layers:
+
+| Signal from Layer 1 (Vision) | + Signal from Layer 3 (A11y) | = Combined Finding |
+|------|------|------|
+| "Low contrast text detected" | "Color contrast ratio 2.1:1 (needs 4.5:1)" | **CRITICAL**: Contrast failure with exact ratio and fix |
+| "Text appears truncated" | — | + Layer 4 (OCR) confirms missing characters → **HIGH** |
+| "Layout looks broken at mobile" | — | + Layer 2 (Diff) shows 42% pixel change → **CRITICAL** regression |
+| — | "Missing form labels" | + Layer 4 (OCR) extracts actual label text → auto-fix with correct text |
+
+## Usage
+
+```bash
+/visual-qa http://localhost:3000                    # Full pipeline (all 5 layers)
+/visual-qa http://localhost:3000 vision             # Vision AI only (fast)
+/visual-qa http://localhost:3000 diff               # Pixel regression only
+/visual-qa http://localhost:3000 a11y               # Accessibility only
+/visual-qa http://localhost:3000 ocr                # OCR text check only
+/visual-qa http://localhost:3000 full --baseline ./baselines  # Full with regression diff
+```
+
+## In Pipes
+
+```bash
+# Visual QA then ship
+/pipe visual-qa http://localhost:3000 ?>> ship !>> fix
+
+# Full dev flow: implement → visual QA → fix issues → ship
+/pipe go *5 >> visual-qa http://localhost:3000 full ?>> pr !>> (fix >> visual-qa) *3?
+
+# Compare staging vs production
+/pipe visual-qa https://staging.app.com diff --baseline ./prod-screenshots >> approve >> deploy
+
+# Accessibility-first workflow
+/pipe hig >> visual-qa http://localhost:3000 a11y >> fix >> visual-qa a11y >> assert "0 a11y violations"
+
+# Full pre-release visual QA
+/pipe browser-test http://localhost:3000 >> visual-qa http://localhost:3000 full >> changelog >> pr
+```
+
+## Output
+
+```
+.luna/{project}/visual-qa/
+  report.md                    # Unified report with all layers
+  screenshots/                 # Captured screenshots (Layer 0)
+    {page}/{viewport}.png
+  vision/                      # Vision AI findings (Layer 1)
+    {page}-analysis.json
+  diffs/                       # Pixel diff overlays (Layer 2)
+    {page}-diff.png
+    {page}-diff-stats.json
+  accessibility/               # WCAG scan results (Layer 3)
+    {page}-a11y.json
+    summary.json
+  ocr/                         # Extracted text (Layer 4)
+    {page}-text.json
+  performance/                 # Perf metrics (Layer 5)
+    {page}-metrics.json
+  correlation/                 # Cross-layer findings (Layer 6)
+    unified-findings.json
+    priority-fixes.md
+```
+
+## Severity Classification
+
+| Severity | Definition | Auto-fix? |
+|----------|-----------|-----------|
+| CRITICAL | Broken layout, missing content, a11y violation blocking users | Yes (3 attempts) |
+| HIGH | Wrong brand, placeholder text, contrast failure, large regression | Yes (2 attempts) |
+| MEDIUM | Minor layout shift, small diff, missing ARIA label | Suggest fix |
+| LOW | Style inconsistency, minor spacing, non-blocking a11y info | Log only |