videoclaw 3.0.0-alpha.1

package/skills/brand-agency/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: brand-agency
+description: |
+  Full creative-agency brand launch inside videoclaw. Use when the user wants
+  a brand campaign from a product photo or website, a "brand kit", a "full
+  brand launch", a locked brand system (palette/voice/typography), or the
+  10-image + 5-video launch package. Orchestrates go-bananas, gen-image
+  --backend flow, vclaw provider routes, and the preview portal; persists the
+  brand system via `vclaw video brand-definition`.
+---
+
+# Brand Agency
+
+Raw product photo (or website URL) → brief → cited market research → locked
+brand system → vision-verified master asset → 10-image brand kit → 5-video
+campaign set → campaign pack. Phase-gated: never advance past a failed gate.
+
+All spends sit behind videoclaw's standard gates (`--dry-run` plan first,
+`--confirm-spend` to render). Never bypass them.
+
+## Phase 0 — Intake
+
+1. Collect the product photo (preferred) or website URL.
+2. `vclaw video init <slug> --mode director` (workspace root per project).
+3. Copy the photo to `projects/<slug>/assets/source/`.
+4. URL input: run `vclaw video brand-extract --project <slug> --url <url>`
+   first; treat `brand-dna.json` as evidence, not the decision.
+
+## Phase 1 — Product brief
+
+Vision-read the photo (Read tool) and fill every field; flag every guess
+`[INFERRED]`. Do not invent features — only what is visible or standard for
+the category.
+
+- Product name (from packaging if visible, else suggest)
+- One-line pitch (what / who for, one sentence)
+- Product category (refined)
+- Brand promise (unsolved problem → hypothesis; research confirms next)
+- Five proof points (confirmable or reasonable for the type)
+- Primary brand color (extracted from packaging)
+- Brand mood, audience, cultural reference brand (+ why)
+
+## Phase 2 — Market research
+
+WebSearch sweep, all cited:
+1. "<category> problem" / "<category> review" on TikTok-via-web + YouTube.
+2. Reddit/forums: the single biggest unsolved complaint in the category.
+3. Meta Ad Library: top active competitor ads + their positioning angles.
+
+Deliver: the ONE unsolved problem (one sentence) with ≥3 cited sources;
+top-3 competitor angles; brief proof points research contradicts (flag for
+removal) or strengthens (swap in). The unsolved problem becomes the campaign
+pillar.
+
+## Phase 3 — Brand definition lock
+
+Author all 9 sections, then persist:
+
+1. Brand name (final)
+2. Positioning: "For [audience] who [problem], [Brand] is the [category] that
+   [differentiator]."
+3. Functional tagline  4. Emotional tagline  5. Community line
+6. Voice rules (words we use / never use, casing, punctuation, tone)
+7. 6-color hex palette — primary, secondary, tertiary background, dark
+   typography accent, metallic, contrast. Give every color a prompt-safe
+   `name` (e.g. "electric blue") — the BRAND prompt line uses names, not hex.
+8. Typography hierarchy — wordmark / display / headline / body / caption,
+   Google-font name + weight each.
+9. 12-week theme map — 3-4-word theme per week, launch-sequenced.
+
+Write the JSON (schema: `schemas/video/artifacts/brand-definition.schema.json`),
+then:
+
+```bash
+vclaw video brand-definition --project <slug> --from-json /tmp/brand.json --write
+```
+
+Fix every problem the validator lists. From here on, `filmmaking-prompts`
+auto-appends the prose BRAND line to every scene packet.
+
+## Phase 4 — Master asset + verify gate (HARD GATE)
+
+1. Generate ONE master packshot. Backend: go-bananas `generate_image`
+   (default) or `vclaw video gen-image --backend flow --model nano-banana-pro`
+   (dry-run first). The prompt must specify: form factor + dimensions, body
+   color by hex, cap/joint detail, surface finish, wordmark text + font weight
+   + position, base treatment, glyph + position, lighting aesthetic, and
+   photographer references (e.g. Carl Kleiner x Aaron Tilley x Hugh
+   Kretschmer).
+2. Vision-verify (Read the rendered image): wordmark spelled correctly; colors
+   match the palette hex; proportions production-ready; nothing distorted.
+   FAIL → state what is wrong, re-roll with corrections (max 3 attempts, then
+   stop and report).
+3. On PASS, register twice:
+   - go-bananas `create_product_reference` → record the id.
+   - Flow Character (flow-register-characters path) → record the exact-case
+     name; product packshots are not faces, so the R2V moderation filter does
+     not apply.
+4. Update the brand JSON with `masterAsset { imagePath, gbProductRef,
+   flowCharacterName, verified: true, verifiedAt }` and re-run
+   `brand-definition --from-json --write`.
+
+Nothing below runs until this gate passes.
+
+## Phase 5 — 10-image brand kit
+
+Generate via go-bananas `generate_with_product` against the registered master
+(brand palette + master lighting on every image). Alternate backend:
+`gen-image --backend flow --character <FlowCharacterName>` (nano-banana-pro,
+≤10-ref budget; character-bundled images count into the same budget).
+
+01 packshot 1:1 · 02 three-variant flat-lay 4:5 · 03 close-up with human
+element 4:5 · 04 billboard hero + tagline lockup 16:9 · 05 reels cover 9:16 ·
+06 surreal floating hero, no copy 4:5 · 07 merch flat-lay 1:1 · 08 key art
+three-product lineup 16:9 · 09 unboxing flat-lay 1:1 · 10 variant/color
+system chart 1:1.
+
+Stage results under `projects/<slug>/images/` (portal-scanned dirs only).
+
+## Phase 6 — campaign films
+
+V1 UGC pain reveal 9:16 · V2 cinematic flagship 16:9 · V3 ASMR unboxing 9:16 ·
+V4 POV demo 9:16 · V5 surreal product hero 16:9.
+
+**Character-led films (a person carries the ad) — use the native Flow R2V lane.**
+This is the preferred path and is its own skill, `character-ad` — invoke it, or
+run the steps directly. Register each person AND the product master as Flow
+Characters once (`vclaw video flow-register-characters`), then render each scene
+straight from those references:
+
+```bash
+vclaw video flow-r2v --project <slug> \
+  --prompt 'Asha looks to camera and says: "Fills the room. Burns clean."' \
+  --character Asha --character <BrandName>Master --out outputs/v2-s1.mp4
+```
+
+`flow-r2v` locks the person + product (character_1..7), Veo generates the voice
++ lip-sync NATIVELY from the dialogue in the prompt (no muxed TTS), and the
+dry-voice + no-baked-music hygiene is applied by default so a post bed sits
+cleanly under the voice. The Veo 3.1 R2V lane CLEARS photoreal human faces
+(live-proven) — register real people directly; one reference locks the face
+across every shot (tighter than per-keyframe i2v). Assemble with
+`vclaw video stitch-ad` (cross-dissolves + instrumental bed laid UNDER the
+voice), then `title-card` + `make-vertical`.
+
+**Product-only films (no person)** stay on `seedance-direct` / `dreamina-useapi`
+with the master product reference (strict identity, no voice needed), or a
+single `flow-r2v --character <BrandName>Master` for a smoke/ember hero beat.
+
+Hard rules: Flow submits SEQUENTIAL (burst → 403 reCAPTCHA; `flow-r2v`
+cool-down-retries); cast names exact-case; lock the product as a second
+`--character` so the wordmark never drifts; verify every clip by CONTENT (extract
+a frame) before assembling — never trust exit codes, and report what actually
+rendered (a failed or dropped scene is stated plainly, never silently
+substituted); a masked "all operations failed" is probabilistic, retry once.
+Renders take minutes — run them in the background and keep working on the next
+phase's free steps; don't block polling a single render.
+
+Cost ladder: drafts on free runway-explore / overnight `batch-submit`;
+character films + finals on Flow Ultra credits / paid routes only after review;
+720p for prototypes.
+
+## Phase 7 — Campaign pack
+
+1. 12-week content calendar: theme map → per-week post copy (voice rules
+   applied) + asset mapping. Write `projects/<slug>/artifacts/campaign-calendar.md`.
+2. Paid-media budget allocation + KPI targets (CPA, repeat rate) →
+   `campaign-plan.md`.
+3. Stage finals under `projects/<slug>/final/...`, then
+   `vclaw video portal --project <slug>` for the brand-book delivery surface.
+
+## Resume
+
+Each phase records its outputs in the project. On re-entry, read
+`brand-definition.json` + project artifacts, report which phases are complete,
+and continue from the first incomplete phase.
+
+Don't end a turn on a promise: if the next phase's inputs are ready and its
+gate has passed, continue into it now. Pause only at the named gates — a spend
+needing approval, the Phase 4 verify gate failing out, or input only the user
+can provide.

package/skills/brand-presenter/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: brand-presenter
+description: Generic narrated presenter-video workflow for turning a slide deck or structured topic into an intro/slides/outro presentation using a branded host profile.
+---
+
+# Brand Presenter
+
+Create a narrated presentation-style video from a PDF or slide deck using a
+branded presenter profile for intro and outro scenes.
+
+## Brand profile
+
+This skill is parametric. Each child skill (`bunty`, `davendra-presenter`,
+`nex-presenter`, future presenters) provides a `brand-profile.json` that
+specializes this workflow for a specific host.
+
+Schema: [`schemas/video/brand-profile.schema.json`](../../schemas/video/brand-profile.schema.json).
+
+When this skill is invoked via a child alias, the orchestrator should:
+1. Load the child's `brand-profile.json`.
+2. Substitute `{{presenterName}}`, `{{characterId}}`, `{{hostPersona}}`,
+   `{{introAsset}}`, `{{outroAsset}}`, etc. throughout the workflow below.
+3. Use `triggerPhrases` to confirm intent routing was correct.
+
+## When To Use
+
+Use this workflow when:
+
+1. a slide deck or PDF needs to become a narrated video
+2. the workflow should include a recurring host character or presenter
+3. a legacy presenter-specific skill such as `davendra-presenter` or
+   `nex-presenter` was requested and should map to one shared implementation
+
+## Generic Flow
+
+1. extract slides
+2. generate narration for each slide
+3. generate intro and outro presenter dialogue
+4. prepare presenter images or bundled assets
+5. animate slides
+6. generate presenter video segments
+7. synthesize narration / voice-change presenter scenes
+8. assemble final video with music and transitions
+
+> **TS-native assembly path (Slice 3i):** `vclaw video assemble --project <slug> [--brand-profile <path>] [--dry-run]`
+> is now the forward path for the assemble stage (step 8 + its inputs 1–7). It runs the
+> in-process pipeline — PDF slides → title card → per-slide animation → TTS narration →
+> background-music bed → FFmpeg stitch — and writes a typed `assemble-report.json`. Run it
+> with `--dry-run` to plan the full pipeline (every FFmpeg command + provider call) without
+> needing ffmpeg or API keys. The Python pipeline under `skills/video-replicator/scripts/`
+> is **superseded for the assemble stage** but retained for now until a future cleanup;
+> prefer the `vclaw video assemble` CLI going forward.
+
+## Brand Profile Inputs
+
+Each brand/presenter profile should provide:
+
+1. presenter name
+2. Go Bananas character id when applicable
+3. default intro/outro assets
+4. preferred voice id / TTS settings
+5. any brand-specific title-card or overlay assets
+
+## Current Bundled Profiles
+
+1. `skills/davendra-presenter/` — business/strategic briefing presenter (Pixar `character_id=109`)
+2. `skills/nex-presenter/` — tech briefing presenter (Pixar `character_id=98`)
+3. `skills/bunty/` — cricket match-recap presenter (Pixar `character_id=97`) — the most actively-developed; canonical source for the shared patterns in the next section
+
+Use those directories as brand-profile overlays on top of this generic
+workflow.
+
+## Guardrails
+
+1. Prefer repo-local skill paths over old `.claude/...` assumptions.
+2. Keep presenter-specific constants in the brand-profile directories instead of
+   duplicating the whole workflow.
+3. Treat the compatibility presenter skills as aliases, not as the canonical
+   place to evolve the workflow.
+
+## Shared learnings from Bunty (cross-pollination hub)
+
+`skills/bunty/` is the most actively-developed presenter and the canonical
+source for the following battle-tested patterns. **Every new presenter profile
+should adopt these where applicable:**
+
+Two standing rules on top of the table below: confirm the render plan (slide
+count / scene count ≈ spend) with the user once before the first paid TTS/Veo
+call, then proceed without re-asking; and frame-verify every rendered slide and
+clip by content before assembly — a failed or dropped item is stated plainly,
+never silently substituted.
+
+| Pattern | Purpose | Status in davendra/nex | Cost to add |
+|---|---|---|---|
+| Pre-flight gates (`bunty_narration_check.py`, `bunty_image_filter_check.py`) | Catch off-by-one beats + Veo filter rejections BEFORE paying for TTS/Veo | added 2026-05-25 | $0.01 + 30s per run |
+| Identity-lock helper pattern (`bunty_helpers.build_*_image_kwargs()`) | Stop character drift on Go Bananas Pro (clean-shaven, wrong hair, etc.) | documented, helpers not yet needed | ~30 LOC per character |
+| Correction-loop recovery (`facts_corrected.txt` → NLM source re-upload) | Fix slides where wrong facts are burned into the PNG | added 2026-05-25 | 1 NLM regen cycle |
+| Render-exactly-once guards in focus prompt | Stop NLM rendering the same slide in 2 different visual styles | bunty-only (cricket-specific examples) | 1 prompt line |
+| Env auto-load at pipeline top | Avoid "forgot to source .env" debugging | bunty-only | 5 LOC |
+| Failed-artifact skip on re-run | Don't re-pay for completed scenes | bunty-only | resume-aware checks |
+| Interactive preview pages (HTML) | Review per-scene assets without scrubbing the final MP4 | bunty-only | 1 HTML template |
+| Surgical re-generation (per-scene TTS / loop / segment regen) | Fix one bad beat without re-running the whole pipeline | added to nex (Phase 10); not in davendra | port from nex Phase 10 |
+| AV parity / frame-aligned concat (`apad=whole_dur` + `-frames:v`) | Stop concat-demuxer DTS drift over 8+ segments | already in davendra + nex via `stitch_bunty.py` reference | inherited |
+
+When a new bunty pattern proves out in production, the cycle is:
+
+1. Land it in `skills/bunty/SKILL.md` + relevant helpers in
+   `skills/video-replicator/scripts/`.
+2. Update this table.
+3. Open a one-paragraph cross-pollination note in the affected
+   presenter SKILL.md files (the "Cross-pollination notes" section at the
+   bottom of `davendra-presenter/SKILL.md` and `nex-presenter/SKILL.md`).
+4. Only port the helper code into a presenter when that presenter
+   actually hits the same problem — speculative ports are noise.

package/skills/build-fix/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: build-fix
+description: Fix build and TypeScript errors with minimal changes
+---
+
+# Build Fix Skill
+
+Fix build and compilation errors quickly with minimal code changes. Get the build green without refactoring.
+
+## When to Use
+
+This skill activates when:
+- User says "fix the build", "build is broken"
+- TypeScript compilation fails
+- the build command or type checker reports errors
+- User requests "minimal fixes" for errors
+
+## What It Does
+
+## GPT-5.4 Guidance Alignment
+
+- Default to concise, evidence-dense progress and completion reporting unless the user or risk level requires more detail.
+- Treat newer user task updates as local overrides for the active workflow branch while preserving earlier non-conflicting constraints.
+- If correctness depends on additional inspection, retrieval, execution, or verification, keep using the relevant tools until the build-fix workflow is grounded.
+- Continue through clear, low-risk, reversible next steps automatically; ask only when the next step is materially branching, destructive, or preference-dependent.
+
+Delegates to the `build-fixer` agent (STANDARD tier) to:
+
+1. **Collect Errors**
+   - Run the project's type check command (e.g., `tsc --noEmit`, `mypy`, `cargo check`, `go vet`)
+   - Or run the project's build command to get build failures
+   - Categorize errors by type and severity
+
+2. **Fix Strategically**
+   - Add type annotations where missing
+   - Add null checks where needed
+   - Fix import/export statements
+   - Resolve module resolution issues
+   - Fix linter errors blocking build
+
+3. **Minimal Diff Strategy**
+   - NO refactoring of unrelated code
+   - NO architectural changes
+   - NO performance optimizations
+   - ONLY what's needed to make build pass
+
+4. **Verify**
+   - Run the project's type check command after each fix
+   - Ensure no new errors introduced
+   - Stop when build passes
+
+## Command Guidance
+
+- Prefer `omx sparkshell` for noisy build/typecheck runs, repository search/listing, and bounded read-only inspection when summary output is enough.
+- Use raw shell when exact stdout/stderr, shell composition, dependency installation, or low-level debugging fidelity is required.
+- If `omx sparkshell` returns incomplete, ambiguous, or `summary unavailable` output, retry with a more precise command or the raw shell immediately.
+
+## Agent Delegation
+
+```
+delegate(
+  role="build-fixer",
+  tier="STANDARD",
+  prompt="BUILD FIX TASK
+
+Fix all build and TypeScript errors with minimal changes.
+
+Requirements:
+- Run tsc/build to collect errors
+- Fix errors one at a time
+- Verify each fix doesn't introduce new errors
+- NO refactoring, NO architectural changes
+- Stop when build passes
+
+Output: Build error resolution report with:
+- List of errors fixed
+- Lines changed per fix
+- Final build status"
+)
+```
+
+## Stop Conditions
+
+The build-fixer agent stops when:
+- Type check command exits with code 0
+- Build command completes successfully
+- No new errors introduced
+
+## Output Format
+
+```
+BUILD FIX REPORT
+================
+
+Errors Fixed: 12
+Files Modified: 8
+Lines Changed: 47
+
+Fixes Applied:
+1. src/utils/validation.ts:15 - Added return type annotation
+2. src/components/Header.tsx:42 - Added null check for props.user
+3. src/api/client.ts:89 - Fixed import path for axios
+...
+
+Final Build Status: ✓ PASSING
+Verification: [type check command] (exit code 0)
+```
+
+## Best Practices
+
+- **One fix at a time** - Easier to verify and debug
+- **Minimal changes** - Don't refactor while fixing
+- **Document why** - Comment non-obvious fixes
+- **Test after** - Ensure tests still pass
+
+
+## Scenario Examples
+
+**Good:** The user says `continue` after the workflow already has a clear next step. Continue the current branch of work instead of restarting or re-asking the same question.
+
+**Good:** The user changes only the output shape or downstream delivery step (for example `make a PR`). Preserve earlier non-conflicting workflow constraints and apply the update locally.
+
+**Bad:** The user says `continue`, and the workflow restarts discovery or stops before the missing verification/evidence is gathered.
+
+## Use with Other Skills
+
+Combine with other skills for comprehensive fixing:
+
+**With Ultrawork:**
+```
+/ultrawork fix all build errors
+```
+Spawns multiple build-fixer agents in parallel for different files.
+
+**With Ralph:**
+```
+/ralph fix the build
+```
+Keeps trying until build passes, even if it takes multiple iterations.
+
+**With Team:**
+```
+/team "debug build failures and fix type errors"
+```
+Uses: explore → build-fixer → verifier workflow.

package/skills/bunty/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: bunty
+description: |
+  "Match Day Analysis with Bunty" — cricket scorecard or play-cricket URL
+  to a narrated video with Bunty (cartoon Indian commentator in orange
+  blazer, character_id=97). Triggers on: cricket scorecards, play-cricket
+  URLs, "Match Day Analysis", "Bunty".
+aliasOf: brand-presenter
+---
+
+# Bunty (brand-presenter specialization)
+
+Bunty is a `brand-presenter` specialization. The full workflow lives in
+[`skills/brand-presenter/SKILL.md`](../brand-presenter/SKILL.md). This
+stub provides the brand parameters that specialize the parent workflow.
+
+**Brand profile:** [`brand-profile.json`](./brand-profile.json) — includes the
+`flowCharacter` recipe (posh BuntyAPI Flow character + the lip-sync prompt template).
+
+**🛑 Interactive gate (ask before any spend):** Bunty is an interactive flow. Before
+rendering, ASK the user (via `AskUserQuestion`): (1) **slide mode** — static (free) vs
+**animated** (subtle F2V motion, ~10 Veo credits/slide via `bunty_animate_slides.py` +
+`stitch_bunty.py --animated`). For animated, offer **one style** (pick from
+`vclaw video animation-styles` — 15 incl. 4 bold) OR **varied mix** (`--varied`):
+slide-type-aware so the title/hero/transition/scorecard slides each move differently
+in one recap instead of all looking the same;
+(2) **result register** (win/loss/tie/youth/abandoned); (3) bookend scenes + posh BuntyAPI
+voice; (4) honour the deck + narration approval gates. Do NOT take defaults silently.
+
+**Trigger:** When a user provides a cricket scorecard PDF, a play-cricket
+URL, or asks for "Match Day Analysis", route to `brand-presenter` with
+this profile loaded.
+
+**Assets:** `assets/` holds Bunty's intro/outro reference images +
+auxiliary character-sheet materials. The brand-profile.json points at
+them.
+
+**Why this stub exists:** prior to Slice 2 (2026-05-25 cutover), Bunty's
+full workflow lived in this SKILL.md as a 560-line copy of the
+brand-presenter pipeline. The duplication is now consolidated in
+`brand-presenter` with this profile-driven specialization.