videoclaw 3.0.0-alpha.1

package/skills/skills-auditor/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: skills-auditor
+description: Audit local VideoClaw skills for production readiness, duplicates, invalid frontmatter, stale paths, missing OpenAI metadata, misplaced resources, and catalog drift.
+---
+
+# Skills Auditor
+
+Use this skill to review the complete local skills ecosystem before shipping or after adding, moving, deleting, or consolidating skills.
+
+## Audit Workflow
+
+1. Inventory skills:
+   - list every immediate `skills/*` directory
+   - verify each top-level directory is an installable skill with `SKILL.md`
+   - confirm no workspaces, benchmarks, generated outputs, or loose resource directories live directly under `skills/`
+2. Validate metadata:
+   - `SKILL.md` frontmatter has only `name` and `description`
+   - `name` matches the folder name
+   - every skill has `agents/openai.yaml`
+   - catalog entries match local folders
+3. Check consolidation:
+   - alias or merged skills do not have local folders unless explicitly internal
+   - old wrapper paths are not referenced by active skills
+   - shared assets live under canonical skills or repo-level scripts
+4. Check portability:
+   - no absolute local paths
+   - no stale `.claude/skills/...` command paths
+   - shell scripts infer the repo root from their own location or accept environment overrides
+5. Verify:
+   - run the skill validator and catalog drift check
+   - run syntax checks for bundled shell/Python scripts
+   - run lint and the relevant tests
+
+## Commands
+
+```bash
+find skills -mindepth 1 -maxdepth 1 -type d ! -exec test -e '{}/SKILL.md' ';' -print
+find skills -maxdepth 2 \( -name README.md -o -name INSTALL.md -o -name QUICK_REFERENCE.md -o -name CHANGELOG.md -o -name VERSION \) -print
+for d in skills/*; do [ -d "$d" ] || continue; [ -f "$d/agents/openai.yaml" ] || printf '%s\n' "$d"; done
+rg -n "\.claude/skills|/Users/|skills/.+-workspace|skills/(bunty|davendra-presenter|nex-presenter|deepsearch|git-master|review|ralph-init|video-analyze-template|video-clone-ad|video-storyboard|video-thumbnail-lab)/" skills src templates package.json -g '!skills/skills-auditor/**'
+npm run check:skills
+```
+
+## Checklist
+
+Read `references/audit-checklist.md` for the full checklist and final report shape.
+
+## Report Format
+
+```markdown
+SKILLS AUDIT REPORT
+
+Inventory:
+- local skills:
+- deleted aliases:
+- moved resources:
+
+Findings:
+- critical:
+- high:
+- medium:
+- low:
+
+Verification:
+- npm run check:skills:
+- npm run lint:
+- tests:
+- script syntax:
+
+Remaining risks:
+- external provider checks:
+- manual review needed:
+```

package/skills/studio-mode/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: studio-mode
+description: Agent-driven video production — interview clarifies intent, consensus plans it, user approves before credits are spent. Invoke for "$studio" requests. Alternative to the fast, one-shot `vclaw video create`.
+---
+
+# Studio Mode — Agent-Driven Video Production
+
+## When to use this skill
+
+- User types `$studio "<description>"` or asks for "studio mode" video creation
+- User wants a more considered, higher-quality video than `vclaw video create` produces
+- User has a rough idea and wants help clarifying before spending credits
+
+## When NOT to use this skill
+
+- User runs `vclaw video create` directly (that's the fast path; don't intercept)
+- User just wants to iterate quickly on a known idea
+
+## Core flow
+
+```
+1. Clarify intent (up to 3 questions) via deep-interview skill
+2. Run consensus planning via `vclaw video studio-plan`
+3. Present plan.md to user; await approval
+4. On approval: run `vclaw video studio-execute <slug>`
+5. Report final video path and cost actuals
+```
+
+## Step-by-step
+
+### Step 1: Parse the user's command
+
+- `$studio "description"` → intent = "description"
+- `$studio "..." --auto` → auto mode (skip user escalation in consensus)
+- `$studio execute <slug>` → skip to Step 4 with existing plan
+- `$studio list` → run `vclaw video studio-list`
+- `$studio status <slug>` → run `vclaw video studio-status <slug>`
+- `$studio clean <slug>` → run `vclaw video studio-clean <slug>`
+
+### Step 2: Smart intent detection + interview
+
+Before running the interview, classify the intent to pick branch-appropriate questions:
+
+- Mentions a platform (TikTok, Shorts, Reels, LinkedIn, etc.)? → skip platform question
+- Mentions characters by name or "character" keyword? → include character-ref question
+- Has a duration ("30 seconds", "1 minute")? → skip duration question
+- Has a style descriptor ("cinematic", "documentary", "UGC")? → skip style question
+
+Then invoke the `oh-my-claudecode:deep-interview` skill with the intent.
+
+**HARD CAP: ask at most 3 questions.** Prioritize the most-ambiguous ones. If the intent is already detailed, ask fewer.
+
+### Step 3: Run consensus planning
+
+After the interview produces a clarified brief, run:
+
+```bash
+vclaw video studio-plan --intent "<clarified brief>" [--auto]
+```
+
+Capture stdout. Three possible outputs:
+
+**Happy path (exit 0, 3 lines):**
+```
+<slug>
+<plan.json path>
+<plan.md path>
+```
+→ Proceed to Step 4.
+
+**Needs user (exit 2):**
+```
+NEEDS_USER
+<session.json path>
+<reason>
+```
+→ Ask user: "The critic keeps flagging [reason]. Would you like me to (1) try again, (2) accept current draft anyway, or (3) tell me what to change?" Act on their choice.
+
+**Failure (exit 1, 3, or 4):** Read stderr, explain to user, exit.
+
+### Step 4: Present plan + gate on approval
+
+Read the plan.md file and print it to the user verbatim. Then ask:
+
+> "Approve this plan? (yes / no / revise)"
+
+- **yes** → proceed to Step 5
+- **no** → exit gracefully. Remind user they can resume later with `$studio execute <slug>`
+- **revise** → ask user what they'd like changed, then re-run Step 2-3 with the additional context
+
+### Step 5: Execute
+
+```bash
+vclaw video studio-execute <slug>
+```
+
+Stream the output to the user. Re-running this command resumes from the last successful scene (mid-run state is checkpointed). Storyboard creation along the way also emits a deterministic `artifacts/story-bible.json` continuity bible (cast, settings, props, scene timeline, and continuity notes); it spends no credits and is regenerated after any director content-fixes. When complete, display:
+
+- Path to final.mp4 (read from `.omx/studio/<slug>/execution.json`)
+- Estimated vs actual cost
+- Any scenes that needed regeneration
+
+### Step 6: Report
+
+Show the user where their video is saved and offer next steps:
+
+- Review the video
+- Run `$studio list` to see all their sessions
+
+## Error recovery
+
+- **LLM call fails during interview:** Fall back to asking the user directly in chat
+- **studio-plan times out:** Tell user, save state, they can re-invoke to resume
+- **Execute fails mid-run:** Tell user to run `$studio execute <slug>` again to resume from the last successful scene
+
+## Key rules
+
+1. **Never spend credits without the approval gate.** User must see plan.md and say yes before Step 5.
+2. **Don't ask more than 3 questions.** If intent is ambiguous, pick the 3 most-unblocking ones.
+3. **Prefer re-invoking over branching.** If user wants a different take, re-run `$studio` with a new intent rather than mutating the current plan.
+4. **Respect auto mode.** If user passed `--auto`, skip confirmation prompts and accept consensus output.
+
+## Example session
+
+```
+User: $studio "cinematic chase scene neon Tokyo"
+Skill: [invokes deep-interview]
+        Q1: What platform — short-form vertical or wide-frame?
+User:   wide-frame
+        Q2: Any character references?
+User:   none
+        Q3: Target duration?
+User:   45 seconds
+Skill:  [runs vclaw video studio-plan --intent "cinematic chase scene neon Tokyo, 16:9, 45s, no characters"]
+        Plan ready:
+
+        ## Plan: cinematic-chase-scene-neon-tokyo
+        **4 scenes · 45s · $4.20 est. · cinematic noir**
+        | # | Duration | Shot | Setting | Mood | Characters |
+        ...
+
+Skill:  Approve? (yes/no/revise)
+User:   yes
+Skill:  [runs vclaw video studio-execute cinematic-chase-scene-neon-tokyo]
+        ...generating scenes...
+        Done. final.mp4 at <root>/projects/cinematic-chase-scene-neon-tokyo/final/final.mp4
+        Actual cost: $4.87 (+$0.67 over estimate)
+```

package/skills/ugc/SKILL.md

@@ -0,0 +1,386 @@
+---
+name: ugc
+description: |
+  UGC Campaign Generator — belief-driven marketing video creation pipeline.
+
+  This skill should be used when:
+  - User asks to "create a UGC campaign", "make UGC ads", "belief-driven ads"
+  - User provides a product URL and wants marketing videos
+  - User mentions "E5 method", "belief journey", "unique mechanism"
+  - User wants multi-video ad campaigns with strategy research
+
+  Output: N belief-targeted UGC videos (30-60s each) with subtitles + campaign report.
+---
+
+# UGC Campaign Generator
+
+*Product URL to belief-driven marketing video campaign.*
+
+## Positioning
+
+Use `skills/video-framework/SKILL.md` as the generic front door for broad video
+requests.
+
+Use `ugc` when:
+
+1. the user explicitly wants UGC ads or belief-driven campaign work
+2. the task is campaign-scale rather than a single video
+3. the E5/belief-method workflow is the right specialization
+
+## Overview
+
+The UGC skill creates belief-driven User-Generated Content style marketing videos. Starting from just a product URL, it autonomously researches the market, crafts belief-targeted scripts using the E5 methodology, and produces N production-ready videos with subtitles.
+
+**Philosophy**: Every marketing campaign is about taking the prospect on a journey to a belief that pre-sells them before the offer is introduced. We craft arguments, not just copy.
+
+## Pipeline: 6 Phases
+
+```
+Phase 0: Setup      — Product refs + cast via the character-creator sub-skill
+Phase 1: Strategy   — Autonomous market research → 4 strategy docs (ugc-strategy agent)
+Phase 2: Scripts    — Belief-driven copywriting → N scripts + storyboards (ugc-brand agent)
+Phase 3: Production — Images → Videos → TTS → Stitch (N ugc-production agents, PARALLEL)
+Phase 4: Subtitles  — vclaw video burn-subtitles (ASS subtitle burn-in)
+Phase 5: Report     — Campaign manifest → HTML report
+```
+
+## Quick Start
+
+```bash
+# The user says: "Create a UGC campaign for [product URL]"
+# Claude Code reads this SKILL.md and orchestrates the full pipeline.
+```
+
+## Agent Architecture
+
+| Phase | Agent | Model | Purpose |
+|-------|-------|-------|---------|
+| 0 | Direct (Claude Code) | — | character-creator sub-skill → `vclaw video character-auto-create` for cast; `vclaw video gen-image` for product refs |
+| 1 | `ugc-strategy` | Opus | Autonomous web research → 4 strategy docs |
+| 2 | `ugc-brand` | Opus | Belief-driven scripts + storyboards |
+| 3 | `ugc-production` (×N) | Sonnet | Video production per script (parallel) |
+| 4-5 | Direct (Claude Code) | — | Subtitles + campaign report |
+
+## Phase 0: Setup
+
+### 0.1 Create Project
+
+```bash
+vclaw video init "{slug}" --mode storyboard
+vclaw video set-meta --project "{slug}" --tag ugc --tag belief-campaign
+```
+
+### 0.5 Create Product Reference (if physical product)
+
+```bash
+vclaw video gen-image --project "{slug}" \
+  --prompt "Professional studio photography of [product], clean white background, commercial quality" \
+  --kind prop --aspect 9:16
+```
+
+### 0.75 Create Character Reference
+
+> **REQUIRED SUB-SKILL: character-creator.** Don't hand-roll character creation
+> here — delegate to the `character-creator` skill, which owns the identity-lock
+> recipe (Input Triad + reference sheet) and drives the canonical CLI.
+
+Create the persistent presenter through the canonical command. Write the cast
+spec to a JSON array, then:
+
+```bash
+# cast.json = [{ "name": "{Campaign}_{Name}", "description": "<30-60 word identity>", "style": "..." }]
+vclaw video character-auto-create --project "{slug}" --input "projects/{slug}/cast.json"
+```
+
+Record the returned character_id into the campaign manifest. (Multi-view
+reference-sheet rendering still runs inside the character-creator sub-skill — see
+its CLI-gap note.)
+
+## Phase 1: Strategy Research
+
+**Agent**: `ugc-strategy` (Opus)
+
+Spawn the strategy agent with the product name and URL. It will:
+
+1. Fetch and analyze the product website (WebFetch)
+2. Conduct market research (WebSearch): competitors, pain points, trends
+3. Create 4 strategy documents:
+   - `projects/{slug}/strategy/research.md` — Market analysis (6+ pages)
+   - `projects/{slug}/strategy/avatar.json` — Customer avatar profile
+   - `projects/{slug}/strategy/offer.json` — Product positioning + unique mechanism
+   - `projects/{slug}/strategy/beliefs.json` — Necessary beliefs ("I believe that...")
+4. Review the resulting strategy docs with the user before production
+5. Present summary and wait for user approval
+
+```bash
+# The clean-room repo does not ship the old UGC strategy helper scripts.
+# Write the research outputs directly under projects/{slug}/strategy/ and keep
+# the production execution on the vclaw CLI surface.
+```
+
+## Phase 2: Belief-Driven Scripts
+
+**Agent**: `ugc-brand` (Opus)
+
+Spawn the brand agent with the strategy documents. It will:
+
+1. Read all strategy documents
+2. Invoke the E5 copywriting methodology (see `references/e5-method.md`)
+3. Create N belief scripts (default 3), each targeting a different necessary belief
+4. Each script follows: Hook → Problem → Mechanism → Proof → Offer → CTA
+5. Validate word counts against duration limits
+6. Save to `projects/{slug}/scripts/belief_N.json`
+
+```bash
+# Store each approved belief script under projects/{slug}/scripts/ and use it
+# as the input source for the current create / iterate / execute flow.
+vclaw video create "Belief 1 UGC script" --project "{slug}" --platform tiktok --aspect-ratio 9:16
+```
+
+### Belief Script JSON Format
+
+```json
+{
+  "script_id": "belief_1",
+  "belief_targeted": "I need a better solution for X",
+  "duration_target": 30,
+  "scenes": [
+    {
+      "scene_number": 1,
+      "type": "hook",
+      "duration": 8,
+      "dialogue": "Speaking text...",
+      "visual": "Visual description...",
+      "camera": "Camera motion...",
+      "veo_prompt": "Full Veo prompt..."
+    }
+  ],
+  "cta": {"text": "Call to action", "url": "https://..."}
+}
+```
+
+### Word Count Limits (CRITICAL)
+
+| Duration | Max Words | Sentences |
+|----------|-----------|-----------|
+| 4 seconds | 8-12 | 1 short |
+| 8 seconds | 15-25 | 1-2 short |
+| 12 seconds | 25-35 | 2-3 sentences |
+
+## Phase 3: Video Production
+
+**Spend checkpoint (once):** before spawning the production agents, confirm with
+the user: N videos × estimated per-video cost. After that approval, run all N
+without re-asking. Frame-verify each finished video by content before it enters
+the report — a failed or dropped video is stated plainly, never silently
+substituted.
+
+**Agent**: `ugc-production` (Sonnet) — spawned once per belief script, runs in parallel.
+
+For each belief script:
+
+### 3.1 Generate First-Frame Images
+
+Identity-locked first frames are keyed on the Go Bananas `character_id` from
+Phase 0.75. The gobananas backend of `vclaw video gen-image` now takes
+`--character-id` (and omits the diegetic-UI directive when it is set, so your
+prompt is authoritative), so generate the keyed frame through the canonical
+command — no raw MCP:
+
+```bash
+# For each scene in the script (--kind prop suppresses baked-in text; --aspect sets format)
+vclaw video gen-image --project "{slug}" --kind prop \
+  --prompt "WIDE HORIZONTAL. [scene visual description]. UGC selfie aesthetic." \
+  --character-id {character_id_from_manifest} --aspect 9:16
+```
+
+### 3.2 Generate Videos
+
+```bash
+vclaw video create "Belief 1 UGC production pass" \
+  --project "{slug}" \
+  --platform tiktok \
+  --aspect-ratio 9:16 \
+  --quality fast \
+  --audio on \
+  --execute
+```
+
+### 3.3 Generate TTS Narration
+
+```bash
+# Keep the transcript in projects/{slug}/audio/tts/ and run the current
+# narration / post-production pass after the base execution succeeds.
+vclaw video status --project "{slug}"
+vclaw video remix-narrated --project "{slug}"
+```
+
+### 3.4 Stitch Final Video
+
+```bash
+vclaw video remix-narrated --project "{slug}"
+vclaw video verify-final --project "{slug}"
+```
+
+## Phase 4: Subtitles
+
+Burn the chosen subtitle style onto the verified render with the canonical
+subtitle command (never a standalone Python script):
+
+```bash
+vclaw video verify-final --project "{slug}"
+vclaw video burn-subtitles --project "{slug}" --subtitle "projects/{slug}/subtitles/belief_1.ass"
+```
+
+### Subtitle Style Presets
+
+| Style | Description | Best For |
+|-------|-------------|----------|
+| `ugc-bold` | Large white text, thick black outline | Social media (Instagram, TikTok) |
+| `ugc-minimal` | Smaller white, subtle shadow | YouTube, professional content |
+| `ugc-tiktok` | Word-by-word yellow highlight | TikTok, short-form content |
+| `ugc-caption` | Standard broadcast captions | YouTube, accessibility |
+
+See `references/subtitle-styles.md` for detailed ASS style definitions.
+
+## Phase 5: Campaign Report
+
+```bash
+vclaw video report --root projects
+vclaw video metrics --root projects
+```
+
+## Project Output Structure
+
+```
+projects/{slug}/
+├── campaign_manifest.json        # Campaign tracking
+├── strategy/                     # Phase 1
+│   ├── research.md
+│   ├── avatar.json
+│   ├── offer.json
+│   ├── beliefs.json
+│   └── hooks.json
+├── scripts/                      # Phase 2
+│   ├── belief_1.json
+│   ├── belief_2.json
+│   └── belief_3.json
+├── veo_specs/                    # Phase 2.5
+│   ├── belief_1_scene_1.json
+│   └── campaign_overview.html
+├── images/                       # Phase 3.1
+│   └── run001_scene_N_frame.jpg
+├── videos/                       # Phase 3.2
+│   └── run001_scene_N.mp4
+├── audio/                        # Phase 3.3
+│   ├── tts/
+│   │   ├── editable_transcript.json
+│   │   └── scene_N_tts.mp3
+│   └── background.mp3
+├── subtitles/                    # Phase 4
+│   └── belief_1.ass
+└── final/                        # Phase 3.4 + 4 + 5
+    ├── belief_1_ugc.mp4
+    ├── belief_1_ugc_subtitled.mp4
+    ├── belief_2_ugc.mp4
+    ├── belief_2_ugc_subtitled.mp4
+    ├── belief_3_ugc.mp4
+    ├── belief_3_ugc_subtitled.mp4
+    └── campaign_report.html
+```
+
+## Orchestration Flow (for Claude Code)
+
+When a user says "Create a UGC campaign for [product]":
+
+### Step 1: Collect Minimal Input
+Ask only:
+- Product/brand name
+- Website or sales page URL
+- (Optional) Number of scripts (default: 3)
+- (Optional) Target country/accent
+
+### Step 2: Phase 0 — Setup
+1. Create project: `vclaw video init`
+2. Scaffold strategy docs manually under `projects/{slug}/strategy/`
+3. Create character reference via Go Bananas MCP (if product has a presenter)
+
+### Step 3: Phase 1 — Strategy
+Spawn `ugc-strategy` agent with product name + URL.
+Wait for completion. Present strategy summary to user. Get approval.
+
+### Step 4: Phase 2 — Scripts
+Spawn `ugc-brand` agent with strategy docs path.
+Wait for completion. Present scripts to user. Get approval.
+
+### Step 5: Phase 3 — Production (PARALLEL)
+For each belief script (1..N), spawn a `ugc-production` agent.
+All agents run in parallel for N× speedup.
+Wait for all to complete.
+
+### Step 6: Phase 4 — Subtitles
+For each final video, run `vclaw video burn-subtitles --subtitle <ass-path>` with the chosen style.
+
+### Step 7: Phase 5 — Report
+Run `vclaw video report` to generate the current clean-room portfolio snapshot.
+Present final deliverables to user.
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Purpose |
+|----------|----------|---------|
+| `ELEVENLABS_API_KEY` | For TTS | Narration generation |
+| `GOOGLE_API_KEY` | For analysis | Video/image analysis |
+
+### Campaign Manifest Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `product_name` | string | Product display name |
+| `product_url` | string | Product website URL |
+| `slug` | string | URL-safe project identifier |
+| `scripts_count` | int | Number of belief scripts (default: 3) |
+| `target_duration` | int | Target per-video duration in seconds (default: 30) |
+| `character_reference` | object | Go Bananas character details |
+| `product_reference` | object | Go Bananas product details |
+| `localization` | object | Country, accent, presenter prefs |
+| `phases_completed` | array | List of completed phase numbers |
+
+## Canonical commands this skill drives
+
+Every stage runs through the `vclaw` CLI — no standalone Python scripts:
+
+| Command | UGC Usage |
+|--------|-----------|
+| `vclaw video create` | Base UGC generation and project scaffolding |
+| `vclaw video execute` | Provider submission for approved runs |
+| `vclaw video soundtrack` | Background music bed |
+| `vclaw video narrate` / `dialogue` | TTS narration / spoken lines |
+| `vclaw video assemble` | All stitch / mix / FFmpeg operations |
+| `vclaw video remix-narrated` | Post-production narrated remix |
+| `vclaw video burn-subtitles` | Subtitle burn-in (replaces the old transcribe / add-subtitles scripts) |
+| `vclaw video gen-image` | Image generation (Go Bananas / OpenAI backends) |
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Strategy agent takes too long | WebSearch may be slow; agent auto-retries |
+| Script word count exceeds limit | Re-cut the belief script before running `vclaw video create` |
+| Character looks different across scenes | Create the cast via the character-creator sub-skill (`vclaw video character-auto-create`) and reuse the same Go Bananas `character_id` with `model_id="gemini-pro-image"` |
+| Subtitles out of sync | Use `--transcript` to provide pre-validated transcript instead of Whisper |
+| Whisper not installed | `brew install openai-whisper` |
+| TTS generated for lip-sync scenes | Keep lip-sync scenes isolated in the approved script before the narration pass |
+| Videos stitch in wrong order | `vclaw video assemble` orders scenes by the storyboard sequence (hook→problem→...→cta) |
+| Campaign manifest missing | Run `vclaw video init` first |
+| Need to re-run one script's videos | Spawn a single ugc-production agent with that script_id |
+
+## References
+
+- `references/e5-method.md` — E5 belief-driven copywriting methodology
+- `references/ugc-prompt-templates.md` — UGC Veo prompt patterns
+- `references/subtitle-styles.md` — ASS subtitle style presets
+- `templates/strategy_schema.json` — Strategy document JSON schema
+- `templates/script_schema.json` — Belief script JSON schema