luna-agents 2.0.1

package/commands/ll-fix.md

@@ -0,0 +1,76 @@
+---
+name: ll-fix
+displayName: Luna Bug Fix
+description: Systematic bug fix — reproduce, failing test, bisect, fix, verify, regression test
+version: 1.0.0
+category: debugging
+agent: luna-code-review
+parameters:
+  - name: bug
+    type: string
+    description: Bug description or error message
+    required: true
+    prompt: true
+  - name: scope
+    type: string
+    description: Project or feature scope
+    required: true
+    prompt: true
+workflow:
+  - reproduce_bug
+  - write_failing_test
+  - bisect_root_cause
+  - implement_fix
+  - verify_fix_passes
+  - write_regression_test
+  - run_full_suite
+  - generate_fix_report
+output:
+  - .luna/{current-project}/fix-report.md
+prerequisites: []
+---
+
+# Luna Bug Fix
+
+Systematic bug fix workflow — no guessing, just science.
+
+## What This Command Does
+
+1. **Reproduce** — understand the bug, find the exact trigger
+2. **Failing Test** — write a test that fails with the current bug
+3. **Bisect** — trace the root cause through code flow
+4. **Fix** — implement the minimal fix
+5. **Verify** — confirm the failing test now passes
+6. **Regression Test** — add edge case tests to prevent recurrence
+7. **Full Suite** — run all tests to ensure no side effects
+8. **Report** — document what broke, why, and how it was fixed
+
+## Fix Protocol
+
+```
+Bug report → Reproduce → Write failing test
+    ↓
+Bisect root cause (read code, add logging, trace flow)
+    ↓
+Implement minimal fix (smallest change that fixes the bug)
+    ↓
+Verify: failing test now passes
+    ↓
+Add regression tests (edge cases, related scenarios)
+    ↓
+Run full test suite → All green → Done
+```
+
+## Usage
+
+```
+/fix "users can't log in after password reset — returns 401"
+/fix "dashboard crashes when org has no team members"
+```
+
+## Rules
+
+- Never fix without a failing test first
+- Minimal fix — don't refactor while fixing
+- Every fix gets a regression test
+- Document the root cause in the fix report

package/commands/ll-flaky.md

@@ -0,0 +1,151 @@
+---
+name: ll-flaky
+displayName: Luna Flaky Test Detector
+description: Detect flaky tests by running them under stress — N iterations, failure pattern analysis, timing capture
+version: 1.0.0
+category: testing
+agent: luna-task-executor
+parameters:
+  - name: command
+    type: string
+    description: "Test command to stress-run (e.g. \"npm test\", \"npx vitest\")"
+    required: true
+    prompt: true
+  - name: runs
+    type: number
+    description: "Number of iterations to run (default: 20)"
+    required: false
+    default: 20
+  - name: parallel
+    type: number
+    description: "Max parallel test runs (default: 4)"
+    required: false
+    default: 4
+mcp_servers:
+  - memory
+  - git
+  - sequential-thinking
+prerequisites:
+  - name: test-runner
+    check: "npm test --help 2>/dev/null || npx vitest --help 2>/dev/null"
+    install: "Ensure your test runner is configured (jest, vitest, playwright)"
+    optional: false
+---
+
+# /flaky — Detect Flaky Tests Under Stress
+
+Run your test suite N times (default 20) in parallel and report which tests fail intermittently. Captures failure patterns, timing distributions, and identifies the root causes of flakiness.
+
+## What It Does
+
+```
+/flaky "npm test"
+    │
+    ├── CONFIGURE
+    │   ├── Parse test command
+    │   ├── Set iteration count (default: 20)
+    │   ├── Set parallelism (default: 4)
+    │   └── Isolate test environment per run
+    │
+    ├── EXECUTE (20 runs, 4 parallel)
+    │   ├── Run 1:  PASS  (2.3s)
+    │   ├── Run 2:  PASS  (2.1s)
+    │   ├── Run 3:  FAIL  auth.test.ts:42  (2.8s)
+    │   ├── Run 4:  PASS  (2.2s)
+    │   ├── ...
+    │   └── Run 20: PASS  (2.4s)
+    │
+    ├── ANALYZE
+    │   ├── Group failures by test name
+    │   ├── Calculate flakiness rate per test
+    │   ├── Identify timing patterns (slow = flaky?)
+    │   ├── Detect common root causes:
+    │   │   ├── Race conditions
+    │   │   ├── Timing-dependent assertions
+    │   │   ├── Shared mutable state
+    │   │   ├── Network dependency
+    │   │   └── Port conflicts
+    │   └── Rank by impact (frequency x suite size)
+    │
+    └── REPORT
+        ├── Flaky test list with failure rates
+        ├── Suggested fixes per test
+        ├── Timing distribution graph
+        └── Overall suite reliability score
+```
+
+## How It Works
+
+1. **Parallel execution**: Runs your test command N times with M parallelism
+2. **Isolation**: Each run gets a clean environment (temp dirs, ports)
+3. **Pattern matching**: Groups failures by test name and error message
+4. **Root cause analysis**: Classifies flakiness type based on failure patterns
+5. **Scoring**: Calculates reliability score (passes / total runs per test)
+
+## Usage
+
+```bash
+/flaky "npm test"                                    # Default: 20 runs, 4 parallel
+/flaky "npm test" --runs 50                          # More iterations for confidence
+/flaky "npx vitest run" --parallel 8                 # Higher parallelism
+/flaky "npx playwright test" --runs 10 --parallel 2  # E2E tests (heavier)
+```
+
+## Use Cases
+
+| Use Case | Command |
+|----------|---------|
+| CI reliability | `/flaky "npm test" --runs 50` |
+| Pre-merge validation | `/flaky "npm test -- --changedSince main"` |
+| Test suite health | `/flaky "npm test" --runs 100` |
+| E2E stability | `/flaky "npx playwright test" --runs 10` |
+| Specific file | `/flaky "npx vitest run src/auth.test.ts" --runs 30` |
+
+## Output Structure
+
+```
+flaky-report/
+├── report.md              # Full flaky test report
+├── results.json           # Raw run data
+├── summary.json           # Flakiness scores
+│   {
+│     "total_runs": 20,
+│     "suite_pass_rate": "95%",
+│     "flaky_tests": [
+│       {
+│         "name": "auth.test.ts > should refresh token",
+│         "pass_rate": "85%",
+│         "failures": 3,
+│         "cause": "race_condition",
+│         "fix": "Add await before token check"
+│       }
+│     ]
+│   }
+└── timing/
+    └── distribution.json  # Per-test timing data
+```
+
+## Flakiness Classification
+
+| Type | Pattern | Fix Strategy |
+|------|---------|-------------|
+| Race condition | Random failures, timing varies | Add proper awaits, locks |
+| Shared state | Fails when run in parallel | Isolate test state |
+| Timing | Fails on slow machines | Use retries, increase timeouts |
+| Network | Fails intermittently | Mock external calls |
+| Port conflict | Fails in parallel | Use random ports |
+
+## In Pipes
+
+```bash
+/pipe flaky "npm test" >> fix >> flaky "npm test" >> assert "flaky == 0"
+/pipe flaky "npm test" >> ghost blog "Fixing Flaky Tests"
+/pipe test >> flaky "npm test" --runs 50 >> guard >> ship
+/pipe flaky "npx playwright test" >> heal >> flaky >> ship
+```
+
+## Reference
+
+- Inspired by: https://github.com/bradfitz/flakestress
+- Jest: `--forceExit --detectOpenHandles` flags help identify leaks
+- Vitest: `--reporter=json` for machine-readable output

package/commands/ll-flow-record.md

@@ -0,0 +1,180 @@
+---
+name: ll-flow-record
+displayName: Luna Flow Record
+description: Record browser flows as demo videos — navigate any site, capture screenshots + video, generate AI narration
+version: 1.0.0
+category: creative
+agent: luna-task-executor
+parameters:
+  - name: url
+    type: string
+    description: URL to record (e.g., https://lunaos.ai or http://localhost:3000)
+    required: true
+    prompt: true
+  - name: flow
+    type: string
+    description: "Flow type: tour (full product), landing (marketing pages), auth (login/signup), dashboard, custom"
+    required: false
+    default: tour
+  - name: output
+    type: string
+    description: "Output format: video (webm), screenshots (png), gif, all"
+    required: false
+    default: all
+mcp_servers:
+  - playwright
+  - zai-mcp-server
+prerequisites: []
+---
+
+# Luna Flow Record
+
+Record any web app's user flows as professional demo videos with AI-generated narration.
+
+## What This Command Does
+
+1. **Analyze** — reads the target URL, detects pages and navigation
+2. **Plan** — creates a flow of pages to visit with timing
+3. **Record** — opens Playwright browser with video recording enabled
+4. **Navigate** — visits each page, scrolls, waits for animations
+5. **Screenshot** — captures every page state at 1280x720
+6. **Narrate** — uses Claw Gateway AI to generate captions per step
+7. **Output** — saves video (.webm), screenshots (.png), and narration (.srt)
+
+## Usage
+
+```bash
+# Record a full product tour
+/flow-record https://lunaos.ai tour
+
+# Record just the landing page sections
+/flow-record https://myapp.com landing
+
+# Record auth flow
+/flow-record https://myapp.com auth
+
+# Record dashboard walkthrough
+/flow-record http://localhost:3000 dashboard
+
+# Screenshots only (no video)
+/flow-record https://lunaos.ai tour screenshots
+```
+
+## How It Works
+
+### Step 1: Detect Pages
+The agent scans the target URL for navigation links, routes, and sections:
+- Extracts all `<a href>` links from the page
+- Identifies hash anchors for single-page sections
+- Detects auth pages (login, signup, forgot-password)
+- Finds dashboard/app routes if authenticated
+
+### Step 2: Generate Flow Script
+Creates a Playwright script that:
+```javascript
+const pages = [
+  { url: 'https://site.com', wait: 2000, caption: 'Homepage' },
+  { url: 'https://site.com/#features', wait: 1500, caption: 'Features' },
+  { url: 'https://site.com/pricing', wait: 1500, caption: 'Pricing' },
+  // ... detected pages
+];
+```
+
+### Step 3: Record with Playwright
+```javascript
+const ctx = await browser.newContext({
+  viewport: { width: 1280, height: 720 },
+  recordVideo: { dir: outputDir, size: { width: 1280, height: 720 } },
+});
+// Navigate each page, wait for content, capture screenshots
+```
+
+### Step 4: AI Narration
+For each screenshot, the agent calls the Claw Gateway:
+```
+System: You are a product demo narrator. Given a screenshot description,
+write a 1-sentence caption for a demo video.
+
+User: Page showing a pricing table with Free ($0), Pro ($29), Team ($79)
+
+AI: "Choose the plan that fits — start free and upgrade as you grow."
+```
+
+### Step 5: Output
+```
+.luna/{project}/flow-record/
+  video.webm          # Full recording (1280x720)
+  screenshots/
+    01-hero.png
+    02-features.png
+    03-pricing.png
+    ...
+  narration.srt       # Subtitle file with AI captions
+  narration.json      # Structured narration data
+  flow.json           # The flow definition (replayable)
+```
+
+## Predefined Flows
+
+### `tour` — Full Product Tour
+Visits: homepage → features → use cases → demo → pricing → login → dashboard → docs
+
+### `landing` — Marketing Pages Only
+Visits: homepage → features → pricing → about → contact → blog
+
+### `auth` — Authentication Flow
+Visits: signup → login → forgot password → OAuth buttons
+
+### `dashboard` — App Walkthrough
+Requires credentials in `.luna/rules.yaml`:
+```yaml
+flow_record:
+  credentials:
+    email: demo@example.com
+    password: DemoPass123!
+```
+
+### `custom` — Define Your Own Flow
+Create `.luna/{project}/flow-record/custom-flow.json`:
+```json
+[
+  { "url": "/", "wait": 2000, "caption": "Welcome" },
+  { "url": "/features", "wait": 1500, "scroll": "bottom" },
+  { "url": "/pricing", "wait": 1500, "caption": "Pricing" }
+]
+```
+
+## Integration with CodeRailFlow
+
+If your project uses CodeRailFlow (flow.coderail.dev), existing flows can be recorded:
+
+```bash
+# Record a CodeRailFlow flow definition
+/flow-record https://myapp.com --coderail-flow flow-id-123
+
+# Use CodeRailFlow's element mapper for precise interactions
+/flow-record https://myapp.com dashboard --use-elements
+```
+
+The agent will fetch the flow definition from CodeRailFlow's API and replay it with video recording enabled.
+
+## In Pipes
+
+```bash
+# Build feature, then record demo
+/pipe go >> flow-record http://localhost:3000 tour >> publish youtube
+
+# Record before and after
+/pipe flow-record https://staging.app.com tour >> deploy >> flow-record https://app.com tour
+
+# Full launch: test, record, publish
+/pipe browser-test http://localhost:3000 >> flow-record http://localhost:3000 tour >> ship
+```
+
+## Tips
+
+- Use `tour` for Product Hunt / investor demos
+- Use `landing` for marketing asset screenshots
+- Use `auth` to verify OAuth buttons look right
+- Videos are 1280x720 (standard HD) — good for embedding
+- Screenshots work as social media cards (OG images)

package/commands/ll-flowdocs.md

@@ -0,0 +1,83 @@
+---
+name: ll-flowdocs
+displayName: Luna Flow & Skills Documentation
+description: Document all user flows, interaction patterns, and skills with Mermaid diagrams
+version: 1.0.0
+category: documentation
+agent: luna-flow-documenter
+parameters:
+  - name: scope
+    type: string
+    description: Project or feature scope for flow documentation
+    required: true
+    prompt: true
+workflow:
+  - discover_user_flows_and_state_machines
+  - trace_interaction_patterns
+  - catalogue_skills_and_agents
+  - generate_mermaid_diagrams
+  - generate_flowdocs_document
+output:
+  - .luna/{current-project}/flowdocs.md
+prerequisites:
+  - source_code
+---
+
+# Luna Flow & Skills Documentation
+
+Documents all user flows, interaction patterns, agent skills, and state machines from your codebase with Mermaid sequence and state diagrams.
+
+## What This Command Does
+
+This command analyses event handlers, state machines, multi-step processes, and agent skills in your code, then produces comprehensive flow documentation with visual diagrams.
+
+## Prerequisites
+
+Requires in your current project:
+- Source code
+
+For richer output, also provide:
+- `.luna/{current-project}/requirements.md`
+- `.luna/{current-project}/design.md`
+
+## Usage Instructions
+
+When you run this command, you'll be prompted for the scope:
+- Press **ENTER** for full-project flow documentation
+- Type **feature-name** for feature-specific flows
+
+## Execution Steps
+
+1. **Flow Discovery**: Finds all user-facing workflows and multi-step processes
+2. **Interaction Tracing**: Maps buttons and actions to their effects and API calls
+3. **Skills Catalogue**: Documents each agent skill with trigger, input, and output
+4. **Diagram Generation**: Creates Mermaid sequence and state diagrams
+5. **Document Generation**: Produces `flowdocs.md` with complete flow registry
+
+## Output Files
+
+Creates in your current project:
+- `.luna/{current-project}/flowdocs.md`
+
+Includes:
+- Flow catalogue with entry points, steps, and exit conditions
+- Mermaid sequence diagrams for key interactions
+- State diagrams for multi-step processes
+- Skills registry with examples
+- Interaction matrix (action → effect → API call)
+- Error flow diagrams
+- Permission map (role → allowed flows)
+
+## Next Steps in Workflow
+
+After flow documentation:
+```
+/luna-onboarding   # Generate onboarding guide from flows
+/luna-test         # Generate test cases from documented flows
+```
+
+## Tips
+
+- Mermaid diagrams render directly in GitHub, Notion, and most documentation tools
+- Flow docs are excellent source material for QA test plans
+- Re-run after adding new features to keep documentation current

package/commands/ll-gamify.md

@@ -0,0 +1,131 @@
+---
+name: ll-gamify
+displayName: Luna Gamify
+description: Turn your codebase into games — code quizzes, team leaderboards, achievement systems, interactive tutorials, escape rooms
+version: 1.0.0
+category: creative
+agent: luna-task-executor
+parameters:
+  - name: mode
+    type: string
+    description: "Mode: quiz (code quiz), leaderboard (team stats), achievements (badges), escape-room (debug challenge), tutorial (interactive), trivia (fun facts)"
+    required: true
+    prompt: true
+  - name: difficulty
+    type: string
+    description: "Difficulty: easy, medium, hard, expert"
+    required: false
+    default: medium
+mcp_servers:
+  - git
+  - memory
+  - sequential-thinking
+  - playwright
+  - elevenlabs
+  - suno
+---
+
+# /gamify — Play With Your Code
+
+Turn your codebase into interactive games, quizzes, challenges, and team competitions. Learn your codebase while having fun.
+
+## Game Modes
+
+### /gamify quiz
+```
+Code Knowledge Quiz:
+├── "What does this function return?" (from your actual code)
+├── "Which service handles billing webhooks?"
+├── "What's the correct order of middleware?"
+├── "Find the bug in this snippet" (real past bugs from git)
+├── "What was the last thing deployed?"
+├── Score tracking + streak bonuses
+├── Sound effects (ElevenLabs)
+└── Victory jingle (Suno) when you ace it
+```
+
+### /gamify leaderboard
+```
+Team Leaderboard (from git activity):
+├── 🏆 Most PRs merged this sprint
+├── 🐛 Most bugs fixed
+├── 📝 Most code reviewed
+├── 🧪 Best test coverage improvement
+├── 🚀 Most features shipped
+├── ⚡ Fastest PR turnaround
+├── 🎯 Longest green CI streak
+├── 🏅 Achievement badges earned
+└── Updated live from git history
+```
+
+### /gamify achievements
+```
+Unlock badges as you code:
+├── 🎖️ "First Blood" — First commit to the repo
+├── 🌅 "Early Bird" — Commit before 7am
+├── 🦉 "Night Owl" — Commit after midnight
+├── 💯 "Perfectionist" — 100% test coverage on a file
+├── 🔥 "On Fire" — 5 PRs merged in one day
+├── 🛡️ "Guardian" — Fixed a security vulnerability
+├── 🎨 "Pixel Perfect" — Zero visual regression
+├── 📚 "Documenter" — Updated docs with every feature
+├── 🏗️ "Architect" — Refactored > 1000 lines
+├── 🎪 "Full Stack" — Committed to all 10 repos
+└── Custom badges definable per project
+```
+
+### /gamify escape-room
+```
+Debug Escape Room:
+├── Luna introduces a real bug from your git history
+├── You have 10 minutes to find and fix it
+├── Hints available (costs points)
+├── Difficulty scales with your skill level
+├── Leaderboard of fastest solvers
+├── Background music (tense soundtrack via Suno)
+└── Victory animation when solved
+```
+
+### /gamify tutorial
+```
+Interactive Codebase Tutorial:
+├── "Welcome to LunaOS! Let's explore..."
+├── Guided tour through architecture
+├── Challenges at each stop (mini quizzes)
+├── Points for correct answers
+├── Narrated by AI voice (ElevenLabs)
+├── Perfect for onboarding new team members
+└── Completion certificate generated
+```
+
+### /gamify trivia
+```
+Fun Facts About Your Code:
+├── "Did you know? This repo has 47,231 lines of code"
+├── "The oldest file is auth.ts, created 2 years ago"
+├── "Team record: 14 PRs merged in a single day"
+├── "Most edited file: Dashboard.tsx (342 commits)"
+├── "Longest function: processWorkflow (87 lines)"
+├── "Total git commits: 1,847"
+└── Presented as animated cards with sound
+```
+
+## Usage
+
+```bash
+/gamify quiz                                              # Code quiz from your repo
+/gamify quiz --difficulty expert                          # Hard mode
+/gamify leaderboard                                       # Team rankings
+/gamify achievements                                      # Show badges
+/gamify escape-room                                       # Debug challenge
+/gamify tutorial                                          # Interactive onboarding
+/gamify trivia                                            # Fun code facts
+```
+
+## In Pipes
+
+```bash
+/pipe collab onboard >> gamify tutorial >> gamify quiz     # Onboard with games
+/pipe collab retro >> gamify leaderboard >> present sprint # Retro with rankings
+/pipe gamify escape-room >> if $solved >> sing "victory!" # Debug then celebrate
+```

package/commands/ll-gemma4.md

@@ -0,0 +1,84 @@
+# Gemma 4 Local AI Setup
+
+Set up Google Gemma 4 for free, local AI inference via Ollama. Zero cost, 256K context, multimodal (text+image+audio).
+
+## Model Variants
+
+| Model | Active Params | Context | Modalities | Best For |
+|-------|--------------|---------|------------|----------|
+| `gemma4:31b` | 30.7B | 256K | Text, Image | Best quality, fine-tuning |
+| `gemma4:26b` | 3.8B (MoE) | 256K | Text, Image | Fastest, low latency |
+| `gemma4:e4b` | 4.5B | 128K | Text, Image, Audio | Edge + voice |
+| `gemma4:e2b` | 2.3B | 128K | Text, Image, Audio | Mobile, IoT |
+
+## Quick Setup
+
+```bash
+# Install Ollama (if not installed)
+curl -fsSL https://ollama.com/install.sh | sh
+
+# Pull Gemma 4 (choose one)
+ollama pull gemma4          # Default (31B, ~18GB)
+ollama pull gemma4:26b      # MoE, fastest (~15GB)
+ollama pull gemma4:e4b      # Edge with audio (~5GB)
+ollama pull gemma4:e2b      # Smallest (~3GB)
+
+# Verify
+ollama run gemma4 "Hello, are you Gemma 4?"
+```
+
+## Integration
+
+Gemma 4 is auto-detected by:
+- **AMLiQ**: `ModelRouter` checks Ollama → routes screening LLM calls for free
+- **LunaOS**: `smart-router.ts` uses gemma4 for free-tier users
+- **Local providers**: `checkOllamaGemma4()` in local-providers.ts
+
+### Environment Variables
+
+```bash
+OLLAMA_HOST=http://localhost:11434   # Default Ollama endpoint
+GEMMA_MODEL=gemma4                   # Model tag (gemma4, gemma4:26b, etc.)
+```
+
+### AMLiQ Cost Savings
+
+| Provider | Cost per 1K screenings | Latency |
+|----------|----------------------|---------|
+| Anthropic Claude | ~$3.00 | ~500ms |
+| Claw Gateway | ~$1.00 | ~300ms |
+| **Gemma 4 local** | **$0.00** | **~50ms** |
+
+## Benchmarks vs Competitors
+
+| Benchmark | Gemma 4 31B | Qwen 3.5 27B | Llama 4 Scout |
+|-----------|-------------|-------------|---------------|
+| AIME 2026 (math) | **89.2%** | 48.7% | — |
+| LiveCodeBench | **80.0%** | — | — |
+| MMMU Pro (vision) | **76.9%** | — | — |
+| Arena AI | **#3 open** | — | — |
+
+## Architecture Highlights
+
+- **Hybrid Attention**: sliding window (1024) + global attention
+- **Per-Layer Embeddings**: residual signal into every decoder layer
+- **Shared KV Cache**: last N layers reuse earlier KV states (less VRAM)
+- **262K vocabulary**: massive token coverage across 140+ languages
+- **Apache-like license**: permissive for commercial use
+
+## Hardware Requirements
+
+| Model | VRAM (Q4) | RAM | Disk |
+|-------|-----------|-----|------|
+| 31B | ~18GB | 24GB+ | 18GB |
+| 26B MoE | ~15GB | 20GB+ | 15GB |
+| E4B | ~5GB | 8GB+ | 5GB |
+| E2B | ~3GB | 4GB+ | 3GB |
+
+## What This Command Does
+
+1. Checks if Ollama is installed
+2. Pulls the appropriate Gemma 4 model based on available VRAM
+3. Verifies the model loads and responds
+4. Tests integration with the current project (AMLiQ screening or LunaOS routing)
+5. Reports cost savings estimate