---
name: aiugc-video-workflow
description: The prime workflow for AI UGC performance ads for mobile apps. Treg generates the creator footage, HyperFrames edits it with real app recordings, the owner reviews each cut with /review, then both exports ship. Use for any new app ad, remake, variant or hook test, end to end.
---

# AIUGC Video Workflow — the prime workflow

Treg (Seedance 2.5 and friends) makes the creator footage. Real app recordings prove the product.
HyperFrames assembles it. The owner reviews every cut in Cut Notes before anything is called final.
Everything else in this kit is a module that this file calls at the right moment:

- `~/.claude/skills/ai-ugc-realism-workflow/SKILL.md` — concept, script, creator card, shot prompts, clip QA scoring. Read at phases 3 to 5 only.
- `~/.claude/skills/app-ugc-ad-editing/SKILL.md` — HyperFrames edit rules and dual-export QA. Read at phase 6 only.
- `review/SKILL.md` — Cut Notes rounds (`/review`, `/review done`). Phase 7.
- `upscale/README.md` next to this file — optional free 2x Real-ESRGAN upscale of 480p raws. Phase 5.
- `treg` skill — catalog search, prices, call mechanics. Never guess a route or price.

## Standing rules (apply in every phase)

1. **Tell the owner the plan before doing it.** At the start of a campaign, and at the start of each phase, send a brief: the steps you are about to take, why each matters, what it costs, and what you need from them. Three to eight lines. Then do the work. Never make the owner guess what is happening.
2. **Ask only what you cannot find.** Settle the app, its claims, available assets, running ads and ratios from the library, config and campaign files first. Then ask the owner the open questions together, in one message, with your recommendation for each.
3. **Truth over polish.** Real UI only (recordings, mockups, screenshots from the authorized library or supplied by the owner). Never generate, redraw or guess UI, ratings, downloads, prices or testimonials. A synthetic creator is never presented as a real customer.
4. **Price before spend.** Show route, duration, quantity, resolution, live estimate and budget impact; get approval; log every job in `cost-log.csv` and `DECISION-LOG.md`. Never top up. Never resubmit a queued job. Standard routes only.
5. **Generation spec:** 9:16, 480p, highest quality the route offers. Final sizes come from HyperFrames (1080x1920 and 1080x1350), never from a second generation.
6. **Preserve everything:** raws, prompts, job ids, editable projects, review rounds. Never overwrite sources. Keep credentials and private URLs out of shared files.
7. **Say what you checked.** A QA line you did not run is not reported as passed. Audio you cannot hear is reported as unchecked.

## Phase 0 — Workspace and tools (once per session)

Check without changing anything: Treg MCP or CLI signed in and `balance`; HyperFrames version (`npx hyperframes --version`); ffmpeg; whisper-cli if transcription is needed; the campaign folder and its records. Report balance and any missing tool in the opening brief. Reference images hosted on treg.to expire after 7 days: re-host from the local copies before reuse.

## Phase 1 — App context and assets

Source of truth is the authorized asset library when the app has one (`config/apps.yaml`: `asset_library_url`, local root, approved CTAs, owner decisions). Build or reuse `APP_PROFILE.md` and `ASSET_MANIFEST.md`; inspect the actual media, not the catalog prose.

If there is no library entry, **ask the owner for the assets** in one message, as a checklist:
app icon and logo (SVG/PNG), App Store link and current listing text, 3 to 6 screenshots, screen recordings of the exact features to show (native resolution, no notifications, 8 to 15 s each), brand colours and font if any, approved claims and anything that must not be said, the CTA, language and target market, existing ads that are running. Record what arrived in `ASSET_MANIFEST.md` and treat missing items as not available, never as something to invent.

## Phase 2 — Concept or reference? (ask first)

Before any reference work, ask the owner one question with three options and your recommendation:

1. **I have a concept** (a feature, a hook idea, a moment). Then: skip the search, write the structured brief from their concept, and offer to pull 3 to 5 references *for that concept or feature* anyway so the pacing and proof order are borrowed from something that already works.
2. **Find me references** for a feature, a concept or the category. Then: search with Treg and show a shortlist.
3. **I already have a reference** (a link, a file, an entry in the asset library's reference section). Then: go straight to measurement.

**Reference search with Treg.** Search by the task ("competitor ads for teleprompter apps", "TikTok videos about recording yourself talking"), then `catalog_get` for the route and price, say the price, and only then call. Sources, in order of usefulness: the owner's reference library in the asset portal; the Meta Ad Library (Facebook and Instagram ads, sort by days running; you only ever see survivors, so longevity is a signal, not proof); TikTok and Instagram organic search for the feature or pain (format and hook ideas, never claims). Present a shortlist of 3 to 6 with: platform, advertiser, days running or views, length, language, one line on why it fits the brief. Download only the ones the owner picks, into `refs/`, and record source and rights in `ASSET_MANIFEST.md` (references are study material, never footage to reuse).

## Phase 2b — Measure the reference

The owner confirms **one** reference. Then measure it before building anything: shot cuts (`ffmpeg select='gt(scene,0.28)'`), mean shot length, transcript (whisper), hook line, on-screen labels, music role. Write `REMAKE_PLAN.md` with a beat-by-beat map. Measuring first is what turns a day of rounds into one pass.

For a new concept rather than a remake, use the realism module's concept test and still write the same beat map.

**Structured brief, not a vague prompt.** Before any script, `BRIEF.md` names: the audience and their moment of need, the one pain, the one claim being tested (sourced), the emotional angle, the proof type (demo, before/after, comparison), the CTA, the ad's job (cold traffic vs. pushing installed users), what must or must not appear this time, and how many pieces by when. Every later decision points back to one of these fields.

## Phase 3 — Script, creator, storyboard (realism module)

- Script: hook in the first 1 to 3 s, problem, product proof, payoff, one CTA. Natural spoken lines, every claim sourced. Write it in the target language and give the owner both languages.
- **Hook variants:** draft 2 to 3 alternative openings for the same body. The first 3 seconds carry most of the result, and a hook swap is one short clip, not a new ad. Vary the first frame and the line, not just the words: a different opening shot (reaction, phone on tripod, text on screen) is a different hook. Default to shipping the main cut plus one hook variant when budget allows; name them `<campaign>-H1`, `-H2` so results can be matched later.
- **One variable per variant.** A variant changes exactly one of: hook, creator, proof order, offer framing, CTA. Two changes at once cannot be read. Variants of a proven ad are a quarter of the work and carry the account's own evidence; prefer them over a new concept when something is already running.
- Creator: an original adult, defined first on paper (continuity card: age range, look, hair, outfit, energy, filming context). Keep a versioned creator bible so the same creator can carry a whole test set; testing the same concept with two creators is a valid variable when the budget allows.
- Voice: test 2 to 3 voices on one line, owner picks. Keep the chosen voice id in `CREATOR_BIBLE.md`.
- Storyboard: 3 to 6 shots, one main action per shot, phone screen shots planned as green plate so real recordings can be composited.
- **Freeze gate:** exact lines, shot list and durations are written down and approved. No metered *video* call before this.

## Phase 3b — Image generation with Treg (creator anchors and start frames)

Images are the first paid step and the cheapest place to get identity right; a weak anchor costs ten times more downstream.

1. `catalog_search` for image generation, `catalog_get` for the candidate routes. Show a short sheet: model, what it is good at, price per image, total for this pack. Typical, re-check live: Gemini 3 Pro Image (reapi, about $0.03 per image, strong faces and natural phone-camera look), Seedream, GPT Image, Flux. Owner approves.
2. **Anchor pack per creator:** 2 to 4 candidates of the main portrait in the real wardrobe and environment, phone-camera look, natural light. Show them to the owner in chat as a contact sheet; the owner picks one (or asks for one retry with one change). Then 2 to 3 companion views of the chosen anchor (three-quarter, outfit detail, seated at the filming spot) so video prompts can assign each a job.
3. **Start frames (only where they matter):** for shots where framing, phone placement or product position must be exact, generate one start frame from the anchor plus the storyboard description; owner approves the contact sheet before any video.
4. Inspect every image: face, hands, age presentation, clothing, crop, nothing that reads as a real identifiable person, no on-screen text or logos. Regenerate weak ones with one variable changed.
5. Host the approved images for Treg (`treg host`, or the route's upload) and note the expiry (treg.to links last 7 days). Save originals in `refs/`, log each call in `cost-log.csv`, record the chosen anchors in `CREATOR_BIBLE.md` and `generation-manifest.json`.

No video call runs until the owner has approved the anchor and any start frames.

## Phase 4 — Generation with Treg

1. **Model recommendation and price sheet.** `catalog_search` for the job, `catalog_get` for every candidate route. Then show the owner one table before anything is spent: model, provider route, what it does best (one short note), what to watch for, measured success rate, price per second at 480p, and **the total for this storyboard** (sum of the planned clip seconds). Recommend one for this video's type and say why. Typical notes, to be re-checked live each time:
   - Seedance 2.5 (reapi): best all-rounder for reference-led creator footage, multi-image references, native speech in many languages; no bitrate control at 480p.
   - Seedance 2.5 (openrouter): same model, cheaper per second, first/last-frame images only (no identity references); good for POV or inserts.
   - Seedance 1 Lite (replicate): cheapest; fine for simple inserts, front-camera feeds, b-roll; weaker faces.
   - Veo (when listed): strongest talking-to-camera speech and gesture; pricier; check reference support.
   - HeyGen avatar (openrouter): one call covers a whole scripted presenter up to 30 s; static framing; use when the piece is a long clean talking head.
   - Kling / Wan (when listed): alternatives for motion-heavy b-roll; verify reference handling.
   The owner picks; the choice and the sheet go in `DECISION-LOG.md`.
2. Quote the batch for the chosen model (one line per clip with seconds and price) and get approval.
3. Generate **one proof clip** first; inspect it; then the batch. Request `generate_audio: false` when the voice is separate.
4. Prompts: one shot, one action, the approved anchor and companions assigned jobs ("@image1 is the creator: same face, hair, outfit; @image2 the outfit detail"), the approved start frame as first frame where one exists, plain green screen on the phone, no on-screen text or logos. End with stability constraints (stable face, unchanged hair and clothing, no distortion). Keep dialogue shots frontal and simple when native speech is used: one sentence per shot, minimal camera motion, no music, and generate two or three short takes and keep the best opening syllable and ending. Phonetic spellings only for a name that is consistently mispronounced. Test the exact language and voice on one clip before the batch.
5. Retry rule: change one variable per retry (frame, prompt, reference). If a detail keeps failing, move it to real footage or post, do not keep prompting.
6. Log each job in `generation-manifest.json` and `cost-log.csv` with the task id, settings, actual cost and `balance` delta.
7. **Show every generated clip right away.** Send the raw files to the owner in chat (SendUserFile) with a contact sheet, one line per clip on what passed and what did not, and the proposed trims. The owner marks keeps, retakes and drops before the edit starts. Retakes follow the one-variable rule. Only approved clips go to HyperFrames.

## Phase 5 — Clip QA and preparation

Score each clip with the realism module's 8 points (believability, coherence, continuity, product truth, motion, audio, ad effect, technical). Reject or repair the smallest faulty part. Trim dead air at clip heads and tails (typically 0.3 to 0.5 s). Transcribe any native dialogue and compare to the script.

Optional, free: upscale the raws 2x with Real-ESRGAN (`upscale/README.md` next to this file) when the owner wants sharper detail; it keeps the exact takes so nothing downstream changes.

## Phase 6 — HyperFrames edit (editing module)

- Creator footage is the emotional anchor; real recordings are the proof. Phone screens: composite the real recording into the generated phone with per-frame tracking and the true screen mask, matched to the scene's softness and tone.
- Captions match the audio heard; brand font; dark pill; safe zones; no overlay in the first 3 s if the placement forbids it.
- Voice first, music ducked under it (carve), 1 s tail fade, light-leak or hard cuts per house style.
- CTA from the approved list; end card from library assets.
- Two editable compositions: 9:16 project and a reframed 4:5 project. Reframe by hand per shot; never stretch.

## Phase 7 — Gate, then owner review rounds

Internal gate before the owner sees it: `hyperframes check` clean; exact dimensions; duration; no black or frozen frames; a frame extracted from every shot; captions clear of faces and UI; audio floor and tail; both ratios checked separately; nothing in the first 3 s that a placement forbids (logos, overlays, watermarks); music licensed for paid use; synthetic presenter not framed as a real customer. **Distinctness:** compare the cut against everything already shipped for this app (palette, rhythm, hook); if it is the same ad made twice, say so and either turn a dial or call it a variant.

Then `/review`: publish the campaign's Cut Notes page, upload a 720p review copy, send the link, and say which cut and round is loaded. When the owner says done, `/review done`: apply every open note, reply on each, re-render both ratios, next round. **Repeat until a round closes with no open notes and the owner confirms.** Hook variants go through the same page as separate rounds or separate pages, named clearly.

## Phase 8 — Output menu, then export

When the last review round closes, ask the owner what to ship as a checklist (AskUserQuestion, multi-select), defaults pre-ticked:

- [x] 9:16 · 1080x1920 · captions (Meta Reels, Stories, TikTok)
- [x] 4:5 · 1080x1350 · captions (Meta feed)
- [ ] 9:16 no-music and 4:5 no-music (for platforms that add their own audio)
- [ ] 1:1 · 1080x1080 (legacy feed placements)
- [ ] Hook variants H2, H3 as separate files
- [x] Local 2x Real-ESRGAN upscale of the raws before the final render (free, sharper creator detail; skip if already done in Phase 5)
- [ ] Raw takes copied alongside the finals
- [ ] Caption file (.srt) and script PDF for the ads manager

Meta Ad Library compatibility is the default: H.264 High, AAC, MP4 with faststart, 30 fps, under 4 GB, 9:16 and 4:5 at 1080 wide. Add a ratio only if a placement needs it; never stretch, always reframe from the HyperFrames project.

Render the ticked items with PNG frame extraction and CRF 13 (or the kit's current best setting), verify each one (dimensions, duration, codec, no black or frozen frames), then deliver.

## Phase 9 — Final folder and hand-over

Every campaign gets its own export folder under the app's final-deliverables directory: `<final-deliverables>/<App>/<campaign-id>/` containing only the ticked outputs, named `<campaign>_<app>_<lang>_<ratio>_<WxH>[_nomusic|_H2].mp4`, a `raw/` subfolder when raws were requested, and `_superseded/` for earlier versions. Nothing else goes in there (no references, no intermediates).

Show the folder to the owner in chat: send the final files with SendUserFile, open the folder (`open "<path>"`), and list the files with sizes and specs in one short table. Hand over: both editable projects, script (both languages), storyboard or remake plan, asset manifest, generation manifest, cost log, QA report, `REVIEW.md`, refinement notes, and a closing brief: what shipped, what it cost, and one line on what could be tested next.

## After delivery (not part of the workflow for now)

Paid testing of the delivered pieces is the owner's call and is not run by this skill. The closing brief ends with one line naming what could be tested next (usually the hook variant); nothing else.

## Required campaign records

`BRIEF.md` or `REMAKE_PLAN.md`, `APP_PROFILE.md`, `ASSET_MANIFEST.md`, `NARRATION.md` or `SELECTED_SCRIPT.md`, `CREATOR_BIBLE.md`, `STORYBOARD.md` or `EDIT_MAP.md`, `generation-manifest.json`, `cost-log.csv`, `DECISION-LOG.md`, `QA_REPORT.md`, `REVIEW.md`, `REFINEMENT_NOTES.md`. Mark unfinished sections as pending; never imply a record is complete when it is not.