@aicopycoders/exodus 2026.11.1100-beta.7 → 2026.11.1100-beta.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/assets/docs/CLAUDE.md +2 -0
- package/assets/docs/PIPELINES.md +2 -0
- package/assets/skills/exodus/SKILL.md +2 -0
- package/assets/skills/exodus-video/SKILL.md +20 -16
- package/assets/skills/swipe/SKILL.md +1 -1
- package/assets/skills/timeline-ad-factory/AGENTS.md +8 -0
- package/assets/skills/timeline-ad-factory/README.md +38 -0
- package/assets/skills/timeline-ad-factory/SKILL.md +132 -0
- package/assets/skills/timeline-ad-factory/reference/00_hook_elements.md +71 -0
- package/assets/skills/timeline-ad-factory/reference/01_elements.md +53 -0
- package/assets/skills/timeline-ad-factory/reference/02_openers.md +83 -0
- package/assets/skills/timeline-ad-factory/reference/03_script_rules.md +83 -0
- package/assets/skills/timeline-ad-factory/reference/04_storyboard.md +153 -0
- package/assets/skills/timeline-ad-factory/reference/05_generation.md +57 -0
- package/assets/skills/timeline-ad-factory/scripts/assemble.py +86 -0
- package/assets/skills/timeline-ad-factory/scripts/contact_sheet.py +76 -0
- package/assets/skills/timeline-ad-factory/scripts/cost_report.py +25 -0
- package/assets/skills/timeline-ad-factory/scripts/gen_images.py +76 -0
- package/assets/skills/timeline-ad-factory/scripts/gen_music.py +36 -0
- package/assets/skills/timeline-ad-factory/scripts/gen_video.py +167 -0
- package/assets/skills/timeline-ad-factory/scripts/gen_vo.py +180 -0
- package/assets/skills/timeline-ad-factory/scripts/kie.py +168 -0
- package/assets/skills/timeline-ad-factory/scripts/review_clips.py +39 -0
- package/assets/skills/timeline-ad-factory/scripts/setup_check.py +54 -0
- package/assets/skills/timeline-ad-factory/scripts/voices.py +2 -0
- package/assets/skills/timeline-ad-factory/templates/project.json +38 -0
- package/assets/skills/ugc-ads/SKILL.md +32 -0
- package/assets/skills/ugc-ads/scripts/run.py +83 -0
- package/assets/skills/ugc-preproduction/SKILL.md +56 -0
- package/assets/skills/ugc-swipe/SKILL.md +34 -0
- package/assets/skills/ugc-template/SKILL.md +40 -0
- package/assets/skills/ugc-write/SKILL.md +33 -0
- package/dist/commands/video-swipe.d.ts +18 -2
- package/dist/commands/video-swipe.js +173 -26
- package/dist/commands/video.js +4 -1
- package/package.json +1 -1
package/assets/docs/CLAUDE.md
CHANGED
|
@@ -100,6 +100,8 @@ The same folder usually also carries **`genesis-bots`** — the *manual* way to
|
|
|
100
100
|
| Skill | When to Use |
|
|
101
101
|
|-------|-------------|
|
|
102
102
|
| `genesis-bots` | The user says bare **"genesis"**, "run the bots", "openclaw", or names a bot slug, and wants to call a Genesis copywriting / research / strategy / image-prompt bot directly. Needs `GENESIS_API_KEY` plus a provider key (`ANTHROPIC_API_KEY` or `OPENROUTER_API_KEY`) in `.env` — see **Dashboard** below. May not be installed in every folder — check for the skill directory before assuming it's there. |
|
|
103
|
+
| `ugc-ads` | UGC talking-to-camera ad scripts (one person talking to their phone), no video: "write me a UGC script", "swipe this UGC ad", "write me a yapper ad". The front door picks one of three ways: `ugc-swipe` (rewrite a UGC ad that already ran), `ugc-template` (one of 19 script types and a hook) or `ugc-write` (from scratch: brief, 8 angles, scripts). They call the `ugc-swipe-agent`, `ugc-template-agent` and `ugc-write-agent` bots through the `genesis-bots` helper script, so they need the same `GENESIS_API_KEY` plus a provider key. A UGC *video* is the **Video** pipeline above; `ugc-preproduction` runs the separate UGC video kit's preproduction sheet. |
|
|
104
|
+
| `timeline-ad-factory` | Animated TIMELINE video ads ("Day 1... Week 2... Month 3") made start to finish on the member's own Kie.ai key, not on Exodus: "make me a timeline ad", "turn this winning ad into timeline ads". It writes the script, storyboards it and renders it with Python scripts and ffmpeg on this computer. It stops for a yes before each stage and shows a price before the video, but re-rendering a failed clip and the music spend without another yes. Run its paid scripts (`gen_images.py`, `gen_vo.py`, `gen_video.py`, `gen_music.py`) in the background and wait for them to finish, and never start a second copy while one is running: a foreground command is stopped after 10 minutes while Kie keeps rendering and charging, and running it again buys the same clips again. Needs `KIE_API_KEY` in `.env` (`npx @aicopycoders/exodus keys pull` writes it when the key is saved in the dashboard). Doesn't use Genesis. "exodus, make a skeleton timeline video" is the **Video** pipeline above. |
|
|
103
105
|
|
|
104
106
|
Route a bare-"genesis" ask to this skill and an "exodus …" ask to the pipelines above — never cross the two. If someone clearly just wants ads and doesn't know which system they have, ask one question ("drive the Genesis bots directly, or run an Exodus pipeline?") rather than guessing.
|
|
105
107
|
|
package/assets/docs/PIPELINES.md
CHANGED
|
@@ -17,6 +17,8 @@ In Claude Code you don't click buttons. You say **"exodus"** plus what you want
|
|
|
17
17
|
| exodus-workflow | Run/build saved multi-node workflows, resolve inbox gate/repair parks, continue sessions, fire triggers, read banks + promote winners |
|
|
18
18
|
| exodus-hooks | Read the Scout library of hook cards — composable filters, one-card detail, pattern matches, CSV export (read-only) |
|
|
19
19
|
| exodus-video | Make a video ad from a script by running a saved video workflow — storyboard gate, pull every piece + manifest, cut it in whatever editor you use, upload, approve (admin-only) |
|
|
20
|
+
| ugc-ads | UGC talking-to-camera ad scripts, no video ("write me a UGC script", "swipe this UGC ad") — the front door to ugc-swipe, ugc-template and ugc-write; calls the UGC bots on Genesis with your own GENESIS_API_KEY plus a provider key. A UGC video is exodus-video; ugc-preproduction runs the separate UGC video kit's sheet |
|
|
21
|
+
| timeline-ad-factory | Animated timeline video ads ("Day 1... Week 2...") made on your own Kie.ai key, not on Exodus ("make me a timeline ad", "turn this winning ad into timeline ads"); a yes before each stage and a price before the video, but re-rendering a failed clip and the music spend without another yes. "exodus, make a skeleton timeline video" is exodus-video |
|
|
20
22
|
| exodus-browse | View History and Surface the Right Run |
|
|
21
23
|
| exodus-drive | Google Drive, Docs, Sheets via the Dashboard's OAuth |
|
|
22
24
|
| exodus-winners | Mine your own Meta ad account for winners (needs the Meta Ads MCP) and import them into Exodus |
|
|
@@ -26,6 +26,8 @@ This skill ROUTES. Read what the user wants, name the destination skill, and han
|
|
|
26
26
|
| List/switch/troubleshoot brands | `exodus-brand` |
|
|
27
27
|
| Read the Scout hook library — "what do my 15×+ hooks have in common", "show me my Spanish on-screen hooks", "why did that reel score 22×", "export my hooks to a spreadsheet" | `exodus-hooks` (read-only; promoting a card is a dashboard act) |
|
|
28
28
|
| Make a video ad, or anything about a Show or a video run — "start a video ad from this script", "is my video run done", "pull the clips and cut them", "upload my cut", "what's wrong with scene 3" (`exodus video`) | `exodus-video` (admin-only on the dashboard; it drives start → storyboard → pull → cut → upload) |
|
|
29
|
+
| Write UGC talking-to-camera ad SCRIPTS, no video yet — "write me a UGC script", "swipe this UGC ad", "write me a yapper ad", "use a UGC template" | `ugc-ads` (the front door: it picks `ugc-swipe`, `ugc-template` or `ugc-write`; they call the UGC bots on Genesis and need `GENESIS_API_KEY` plus a provider key in `.env`). Turning a finished script into a video is the row above (`exodus-video`), or `ugc-preproduction` when the member runs the separate UGC video kit ("run the preproduction sheet") |
|
|
30
|
+
| Make an animated TIMELINE video ad on the member's own Kie.ai key, without the word "exodus" — "make me a timeline ad", "a skeleton timeline ad", "a Day 1 / Week 2 / Month 3 ad", "turn this winning ad into timeline ads" | `timeline-ad-factory` (Mario's skill: script, storyboard and video on the member's own `KIE_API_KEY` in `.env`; it stops for a yes before each stage and shows a price before the video, but re-rendering a failed clip and the music spend without another yes; it does not use Exodus's video engine). "exodus, make a skeleton timeline video" is the video row above (`exodus-video`, its skeleton timeline template) |
|
|
29
31
|
| See past runs / find an output | `exodus-browse` |
|
|
30
32
|
| Open or create Google Docs/Sheets | `exodus-drive` |
|
|
31
33
|
| Read their OWN live Meta ads and their numbers — "what are my cheapest ads", "where is my spend going", "show me that ad", "what are people saying in the comments on my ads" (`exodus ads` / `exodus comments`) | `exodus-ads` (read-only; already synced by the dashboard, no Meta MCP needed) |
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: exodus-video
|
|
3
|
-
description: Make a video ad with Exodus from the terminal. One sentence ("swipe this ad as a microdrama for my brand", "make this a UGC video") is walked through the template door stop by stop, with a yes asked before each paid step. A competitor's video ad (a file, a link, or an ad in Exodus) is swiped with `exodus video swipe`, as Swipe a video does on the dashboard: broken down, matched to a kind of ad, read first, then one sheet of choices and one yes for the write and the whole video (or, when the member asks, step by step with a yes before each paid step). With no ad named ("find some ads to swipe for this product, give me options"), it first lists the video ads in the brand's swipe library with `exodus video swipe find` and offers at most six. The main path is script-first: run a saved video workflow with `npx @aicopycoders/exodus workflow run`. You read and approve the storyboard, pull every finished piece (per-scene clips, the narration track and per-scene voice, keyframes, cast identity stills, word timings, the music bed) into a folder with `exodus video pull`, and upload a finished cut for approval. Exodus makes the pieces; the cut is made outside it, in whatever editor the user wants — this skill hands over the pieces and the facts about them, it does not prescribe an editor. Use it whenever the user has invoked Exodus and wants anything to do with a video ad, an ad run's clips or storyboard, "pull the pieces", "stitch it together", "make the cut", "upload my cut", or checking on a video run ("exodus, make a video ad from this script", "exodus, is my video run done", "exodus, pull the clips for run X and cut them", "exodus, what's wrong with scene 3", "exodus video status"). Also use it when the user ran an `npx @aicopycoders/exodus video` command or the `exodus` hub skill routed here. Admins get every video command; beta testers with video switched on get start, swipe, status, storyboard, approve, voices, retry-frame, pull and upload on their own brands (see "Beta testers"). "video isn't enabled for this key" means the run id is wrong, the command is admin-only, or video isn't switched on for that dashboard user, so check the id and then say so; do not retry. Never claim generic video-editing asks ("edit this mp4", "add captions to my reel") without Exodus context; in shared folders those belong to the user's other tools. Running or authoring workflows generally is `exodus-workflow`; static image ads are `exodus-image`; copy is `exodus-write`.
|
|
3
|
+
description: Make a video ad with Exodus from the terminal. One sentence ("swipe this ad as a microdrama for my brand", "make this a UGC video") is walked through the template door stop by stop, with a yes asked before each paid step. A UGC script with no video ("write me a UGC script", "swipe this UGC ad" for a script) is `ugc-ads`, and the separate UGC video kit's sheet ("run the preproduction sheet") is `ugc-preproduction`, not this skill. A timeline ad asked for without "exodus" ("make me a timeline ad", "turn this winning ad into timeline ads") is `timeline-ad-factory`, on the member's own Kie.ai key; "exodus, make a skeleton timeline video" stays here. A competitor's video ad (a file, a link, or an ad in Exodus) is swiped with `exodus video swipe`, as Swipe a video does on the dashboard: broken down, matched to a kind of ad, read first, then one sheet of choices and one yes for the write and the whole video (or, when the member asks, step by step with a yes before each paid step). With no ad named ("find some ads to swipe for this product, give me options"), it first lists the video ads in the brand's swipe library with `exodus video swipe find` and offers at most six. The main path is script-first: run a saved video workflow with `npx @aicopycoders/exodus workflow run`. You read and approve the storyboard, pull every finished piece (per-scene clips, the narration track and per-scene voice, keyframes, cast identity stills, word timings, the music bed) into a folder with `exodus video pull`, and upload a finished cut for approval. Exodus makes the pieces; the cut is made outside it, in whatever editor the user wants — this skill hands over the pieces and the facts about them, it does not prescribe an editor. Use it whenever the user has invoked Exodus and wants anything to do with a video ad, an ad run's clips or storyboard, "pull the pieces", "stitch it together", "make the cut", "upload my cut", or checking on a video run ("exodus, make a video ad from this script", "exodus, is my video run done", "exodus, pull the clips for run X and cut them", "exodus, what's wrong with scene 3", "exodus video status"). Also use it when the user ran an `npx @aicopycoders/exodus video` command or the `exodus` hub skill routed here. Admins get every video command; beta testers with video switched on get start, swipe, status, storyboard, approve, voices, retry-frame, pull and upload on their own brands (see "Beta testers"). "video isn't enabled for this key" means the run id is wrong, the command is admin-only, or video isn't switched on for that dashboard user, so check the id and then say so; do not retry. Never claim generic video-editing asks ("edit this mp4", "add captions to my reel") without Exodus context; in shared folders those belong to the user's other tools. Running or authoring workflows generally is `exodus-workflow`; static image ads are `exodus-image`; copy is `exodus-write`.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Video: make the pieces, cut the ad, hand it back
|
|
@@ -700,17 +700,18 @@ step 3 comes once every video has started:
|
|
|
700
700
|
to "End: watch and approve" (pull, cut, upload, the run page). A run that
|
|
701
701
|
stopped at the storyboard goes to stop 3, then the end.
|
|
702
702
|
|
|
703
|
-
**Never start the same swipe twice.**
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
703
|
+
**Never start the same swipe twice.** One swipe is one video. A start of a
|
|
704
|
+
swipe that already has a video is refused, starts nothing, and names the run:
|
|
705
|
+
follow that run with `exodus video status <runId>`. `--again` makes a second,
|
|
706
|
+
paid video from the same swipe: use it only when the member asks for a second
|
|
707
|
+
video. Before writing again after a write whose wait was cut off, run
|
|
708
|
+
`exodus video swipe list`. It lists the newest first, each with when it was
|
|
709
|
+
written and its product, and the writes run one at a time, so a row for that
|
|
710
|
+
ad and product above the last swipe id you noted (any row for it, when you
|
|
711
|
+
noted none), with no run and not marked refused, is that write. Show it with
|
|
712
|
+
`exodus video swipe show <swipeId>` and start it instead of writing again. A
|
|
713
|
+
row marked refused is that write's refusal: report it as a refused write. When
|
|
714
|
+
no such row is there yet, the write may still finish: check again later.
|
|
714
715
|
|
|
715
716
|
At the end, report each video on one line: its ad and persona, its run id
|
|
716
717
|
and its `Watch it:` link, or why it stopped.
|
|
@@ -927,7 +928,8 @@ after their yes.
|
|
|
927
928
|
`--title "<name>"` names the ad, for admins only: a beta tester leaves it
|
|
928
929
|
off, or the CLI refuses it with one sentence naming it. With `--one-shot`
|
|
929
930
|
it buys the whole video with no stop: ask before passing it. `--wait` waits until the run needs the
|
|
930
|
-
member.
|
|
931
|
+
member. A swipe that already has a video is refused, with its run; a
|
|
932
|
+
second video from it needs `--again` and the member's yes to a second video.
|
|
931
933
|
6. **Then** stop 3 (the storyboard) and the end, as above.
|
|
932
934
|
|
|
933
935
|
### Every swipe command
|
|
@@ -942,10 +944,12 @@ exodus video swipe products the brand's products a
|
|
|
942
944
|
exodus video swipe write <breakdownId> --product <id> [--mode <mode>] [--closeness <step>] [--look <slug>] [--script <file>] [--yes]
|
|
943
945
|
the brand's version (member's key); waits for it
|
|
944
946
|
exodus video swipe show <swipeId> one swipe again
|
|
945
|
-
exodus video swipe list the brand's newest swipes
|
|
947
|
+
exodus video swipe list the brand's newest swipes, each with when it was written and its product;
|
|
948
|
+
a refused one shows what it cost
|
|
946
949
|
exodus video swipe find [--brand "<name>"] [--limit <n>] video ads in the swipe library to offer as options (free); no kind, no results
|
|
947
|
-
exodus video swipe start <swipeId> [--style <look>] [--title "<name>"] [--music] [--one-shot] [--yes] [--wait]
|
|
948
|
-
start the run on the kind the swipe wrote
|
|
950
|
+
exodus video swipe start <swipeId> [--style <look>] [--title "<name>"] [--music] [--one-shot] [--again] [--yes] [--wait]
|
|
951
|
+
start the run on the kind the swipe wrote; --again for a
|
|
952
|
+
second, paid video of a swipe that already has one
|
|
949
953
|
exodus video swipe run --sheet <file> [--status] [--persona <name>] [--yes] [--retry-refused] [--wait] every video of a sheet saved as a JSON file
|
|
950
954
|
```
|
|
951
955
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: swipe
|
|
3
|
-
description: Swipe a winning ad (spoken or sung: micro-dramas, Suno song ads, jingles) for the active brand at a chosen closeness. Trigger on "swipe", "swipe this", "swipe this song ad", "swipe this Suno ad", "swipe this jingle", "rip this ad", "make this ours", "same scene, our product", "/swipe", a level ("L1", "level 2"), or the user pasting an ad, a transcript, or a video link (Atria, Facebook Ad Library, TikTok, YouTube) and naming a product. Two doors for the source: an ad already in Exodus (mined or in the swipe library) or a link / paste. Asks five quick questions with a recommendation, then calls the swipe bot on Genesis. Not for writing from scratch (exodus-write), not for why an ad works (anatomy-of-ads), not for the competitor watch list (`exodus swipe brands|run|mine`), not for a swipe straight into a video ("swipe this ad as a microdrama": exodus-video), not for anything that asks how the swipe bot works.
|
|
3
|
+
description: Swipe a winning ad (spoken or sung: micro-dramas, Suno song ads, jingles) for the active brand at a chosen closeness. Trigger on "swipe", "swipe this", "swipe this song ad", "swipe this Suno ad", "swipe this jingle", "rip this ad", "make this ours", "same scene, our product", "/swipe", a level ("L1", "level 2"), or the user pasting an ad, a transcript, or a video link (Atria, Facebook Ad Library, TikTok, YouTube) and naming a product. Two doors for the source: an ad already in Exodus (mined or in the swipe library) or a link / paste. Asks five quick questions with a recommendation, then calls the swipe bot on Genesis. Not for writing from scratch (exodus-write), not for why an ad works (anatomy-of-ads), not for the competitor watch list (`exodus swipe brands|run|mine`), not for a swipe straight into a video ("swipe this ad as a microdrama": exodus-video), not for a UGC talking-to-camera script ("swipe this UGC ad"): ugc-ads, not for anything that asks how the swipe bot works.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Swipe
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
# Agent instructions (Codex)
|
|
2
|
+
|
|
3
|
+
When the user asks for a timeline ad, a Day 1 / Week 2 / Month 3 ad, a skeleton or Pixar timeline ad, or to turn a winning ad (brief, sales page link, or transcript) into timeline ads:
|
|
4
|
+
|
|
5
|
+
1. Read `timeline-ad-factory/SKILL.md` in full and follow it exactly, stage by stage.
|
|
6
|
+
2. Read each `timeline-ad-factory/reference/*.md` file at the stage where SKILL.md tells you to.
|
|
7
|
+
3. Run the Python scripts from the project's top folder, e.g. `python timeline-ad-factory/scripts/gen_vo.py projects/<name>`.
|
|
8
|
+
4. Stop at every gate marked STOP and wait for the user's explicit approval before spending money.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Timeline Ad Factory: setup
|
|
2
|
+
|
|
3
|
+
Turn a brief, a sales page, or the transcript of ANY winning ad into a finished, voiced, captioned timeline video ad. Built for Claude Code or Codex. Runs on one Kie.ai account.
|
|
4
|
+
|
|
5
|
+
## What you need
|
|
6
|
+
|
|
7
|
+
1. **Claude Code or Codex**, installed and signed in.
|
|
8
|
+
2. **A Kie.ai account with credits.** (Optional: an ElevenLabs API key, if you'd rather voice your ads on ElevenLabs directly, or as a backup when Kie's voice service is down.)
|
|
9
|
+
**Kie:** Sign in at kie.ai, open API Keys, and copy your key. One 60-90 second ad on Google Omni usually costs a few dollars in video, plus cents for images, voice and music.
|
|
10
|
+
3. **Python 3.9+** and **ffmpeg** on your computer. The skill checks both on first run and walks you through installing anything missing.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
**Claude Code:** copy this whole `timeline-ad-factory` folder into `~/.claude/skills/` (Mac) or `C:\Users\<you>\.claude\skills\` (Windows). Restart Claude Code. Then just ask: *"Make me a timeline ad for [product]"* or *"Turn this winning ad into timeline ads: [paste transcript]"*.
|
|
15
|
+
|
|
16
|
+
**Codex:** put this folder inside the project folder you work in, and keep the `AGENTS.md` file from this folder at the top of that project (or paste its contents into your existing `AGENTS.md`). Then ask the same way.
|
|
17
|
+
|
|
18
|
+
## First run
|
|
19
|
+
|
|
20
|
+
The skill runs `python scripts/setup_check.py`, which checks your tools and asks for your Kie.ai key once. The key is saved to a `.env` file in your folder. Keep that file private.
|
|
21
|
+
|
|
22
|
+
## How a run goes
|
|
23
|
+
|
|
24
|
+
1. **Elements:** it pulls the winning variables out of your input and proposes 3 angles. You pick.
|
|
25
|
+
2. **Script:** it writes the timeline script and self-checks it. You approve or edit.
|
|
26
|
+
3. **Storyboard:** it casts a voice that fits your market, designs the character and the set, and plans every shot. You approve.
|
|
27
|
+
4. **Images:** character sheet first (you approve), then every storyboard frame (you approve).
|
|
28
|
+
5. **Video:** voiceover, a cost estimate (you say go), clips on Google Omni by default, music, final edit with captions and date stamps, and the real cost.
|
|
29
|
+
|
|
30
|
+
Nothing that costs real money runs until you say yes.
|
|
31
|
+
|
|
32
|
+
## Omni or Seedance?
|
|
33
|
+
|
|
34
|
+
Default is **Google Omni**: about 11x cheaper than Seedance at the same resolution, and close enough in motion for testing. When an ad wins, you can re-render it on **Seedance 2.5** for extra motion: *"re-render this ad on Seedance at 720p"*.
|
|
35
|
+
|
|
36
|
+
## Files in each project
|
|
37
|
+
|
|
38
|
+
`projects/<name>/` holds `project.json` (every decision), `script.txt`, `images/`, `audio/`, `videos/`, `final/ad.mp4`, and `tasks.log` (every paid job, used for the cost report).
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: timeline-ad-factory
|
|
3
|
+
description: Plans, scripts, storyboards and renders animated TIMELINE video ads ("Here's what happens when X takes Y for 30 days... Day 1... Week 2...") from a brief, a sales page link, or the transcript of another winning ad. Use when the user wants a timeline ad, a skeleton/Pixar timeline ad, a Day 1 / Week 2 / Month 3 ad, or wants to turn a winning ad into timeline ads. Runs on one Kie.ai API key. Defaults to Google Omni for video, with Seedance as an upgrade option.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Timeline Ad Factory
|
|
7
|
+
|
|
8
|
+
You are a creative director and producer for animated timeline video ads. You take the user from a raw input to a finished, captioned, voiced video ad, and you stop for the user's approval before every step that costs money.
|
|
9
|
+
|
|
10
|
+
Works in Claude Code and Codex. Everything runs through the Python scripts in this skill's `scripts/` folder plus one Kie.ai API key.
|
|
11
|
+
|
|
12
|
+
**Paths:** `<skill>` below means this skill's own folder. Run every command from the USER's working folder (where their projects live), e.g. `python <skill>/scripts/gen_vo.py projects/<name>`. Projects go in `projects/<name>/` inside the user's working folder, never inside the skill folder.
|
|
13
|
+
|
|
14
|
+
## The five stages
|
|
15
|
+
|
|
16
|
+
1. **ELEMENTS:** pull the winning variables out of the input, build the hook element menu, and write 20+ opening lines.
|
|
17
|
+
2. **SCRIPT:** write the timeline script and run the self-check.
|
|
18
|
+
3. **STORYBOARD:** cast the voice and character, and plan every shot.
|
|
19
|
+
4. **IMAGES:** generate the character sheet and the storyboard frames.
|
|
20
|
+
5. **VIDEO:** generate the clips, the voice, the music, and assemble the final ad.
|
|
21
|
+
|
|
22
|
+
Do them IN ORDER. Never skip a gate. Each gate is marked **STOP**: show the user the work, wait for an explicit yes or edits, then continue.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## Stage 0: Setup (first run only)
|
|
27
|
+
|
|
28
|
+
1. Run `python <skill>/scripts/setup_check.py`. It checks Python 3.9+, Pillow and ffmpeg, then checks for the user's **Kie.ai API key** in `.env` in the project folder. If it's missing, the user adds it with `npx @aicopycoders/exodus keys pull` or by pasting it into `.env` themselves (never ask for the key in the chat, never print the key back, never commit it).
|
|
29
|
+
- If ffmpeg is missing, walk the user through installing it in plain English (Mac: `brew install ffmpeg`; Windows: `winget install Gyan.FFmpeg`, then reopen the terminal). Assume the user is NOT technical.
|
|
30
|
+
- Where to get a key: kie.ai, sign in, then API Keys. They need credits loaded.
|
|
31
|
+
2. Create a project folder for this ad: `projects/<short-name>/`. All files for this ad live there. Copy `<skill>/templates/project.json` into it.
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## Stage 1: ELEMENTS
|
|
36
|
+
|
|
37
|
+
**Input can be any of these:**
|
|
38
|
+
- **A brief:** product, who it's for, the offer.
|
|
39
|
+
- **A sales page link:** fetch it. If fetching fails or the page is blocked, ask the user to paste the page text.
|
|
40
|
+
- **A transcript of another winning ad** in ANY format (micro-drama, UGC, yapper, Suno song, static headline). This is **Trigger Hunting**: the winner proves which variables work on that market.
|
|
41
|
+
|
|
42
|
+
**Read `reference/01_elements.md` in full**, then extract every variable you can find:
|
|
43
|
+
segment, situation, pain points, objections, wrong suspect + real villain, failed fixes, desired outcome, witness, identity payoff, mechanism picture. Use the market's own words. Never invent claims, numbers, or results the input doesn't support.
|
|
44
|
+
|
|
45
|
+
**Read `reference/00_hook_elements.md` and `reference/02_openers.md` in full.** Then build the Hook Bank for this product:
|
|
46
|
+
1. **The element menu:** many options for each high-leverage element:
|
|
47
|
+
- WHO it's for (at least 6 segments) and 2-3 ways to describe each;
|
|
48
|
+
- the pain points and several ways to describe each (clinical, physical, emotional, situational);
|
|
49
|
+
- the consumption verb (5+ that fit the product and segment);
|
|
50
|
+
- the solution, described three ways: NAMED (the brand), GENERAL (the category), and BLIND (color, texture, flavor, exotic origin, or a true comparison like "a fruit" or "a spice already in your kitchen");
|
|
51
|
+
- the hook timeline (start short: 14 or 30 days).
|
|
52
|
+
2. **20+ numbered opening lines** combining those elements across at least 5 opener types, mixing named, general and blind solutions. Label each line with its opener type and solution mode.
|
|
53
|
+
3. **Your top 5 picks** and why.
|
|
54
|
+
|
|
55
|
+
**STOP.** Show the element menu and the opening lines. Wait for the user to pick a line (or mix elements into a new one).
|
|
56
|
+
|
|
57
|
+
Save the variables and the chosen hook to `project.json` (`elements`, `angle`). Save ALL the opening lines to `hooks.md` in the project folder: they're ready-made hook variations to test on the same ad body later.
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## Stage 2: SCRIPT
|
|
62
|
+
|
|
63
|
+
**Read `reference/03_script_rules.md` in full.** Then write the voiceover script:
|
|
64
|
+
- The milestone ladder in the right order (small and private first, visible and social in the middle, big numbers and identity last).
|
|
65
|
+
- Milestones mined from what they WANT and from the objections that stop them.
|
|
66
|
+
- **The AOV trick:** even when the hook says 14 or 30 days, carry the results out to Month 2 and Month 3 and make them COMPOUND, so buying several bottles feels like the obvious move.
|
|
67
|
+
- Mechanism placement: either ingredient credits inside the milestones, or results-only timeline with the explanation after. Pick one and say which.
|
|
68
|
+
- One short spoken line per line of the file. Write for the ear.
|
|
69
|
+
- Length: ~390 words is ~2:30. Ask the user for a target length if they didn't give one (60-90s is a strong default for testing = ~160-240 words).
|
|
70
|
+
|
|
71
|
+
Run the **self-check** at the bottom of `03_script_rules.md` and fix every failure before showing the user.
|
|
72
|
+
|
|
73
|
+
**STOP.** Show the script with the beat labels in the margin, word count, estimated runtime, and the self-check results. Wait for approval or edits. Apply edits exactly as given.
|
|
74
|
+
|
|
75
|
+
Save the approved script to `script.txt` (spoken lines only, one per line, no beat labels) and the labeled version to `script_labeled.md`.
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## Stage 3: STORYBOARD
|
|
80
|
+
|
|
81
|
+
**Read `reference/04_storyboard.md` in full.**
|
|
82
|
+
|
|
83
|
+
1. **Cast the voice.** Pick a voice that fits THIS script and market (narrator gender, age, energy, accent) from the voice list in `04_storyboard.md`. Never default to the same voice for every ad. Give your pick plus one backup and say why, with the preview link for each. Ask which voice provider they want: **Kie** (default, no extra account) or **ElevenLabs** (their own ElevenLabs key; one continuous read with exact word timing). Save it as `voice.provider`.
|
|
84
|
+
2. **Design the character(s)** and the **set**: a short list of distinctive, nameable costume pieces, a fixed set description, the art style (default: Pixar-style 3D; skeletons, monsters and talking objects work great for timeline ads), and the aspect ratio (default 9:16 for feed ads; ask).
|
|
85
|
+
3. **Plan the shots.** Group consecutive script lines into shots. Every line gets a physical action that literally DOES the line. Every panel passes the **Director Test** in `04_storyboard.md`: what each character faces, which way they move and where the camera is, what's in their hands, and physically correct body mechanics. Write 1-3 panels per shot and a beats list. Mark which lines carry a date stamp (DAY 1, WEEK 2...).
|
|
86
|
+
|
|
87
|
+
**STOP.** Show the voice pick, the character + set description, and the full shot plan as a table (shot, lines, panels, stamp). Wait for approval.
|
|
88
|
+
|
|
89
|
+
Save everything into `project.json` (`voice`, `style`, `aspect_ratio`, `character`, `extra_cast`, `set`, `shots`, `stamps`, `end_card`).
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## Stage 4: IMAGES
|
|
94
|
+
|
|
95
|
+
1. `python <skill>/scripts/gen_images.py projects/<name> --sheet` renders the character sheet (plus any extra cast).
|
|
96
|
+
|
|
97
|
+
**STOP.** Show the sheet image(s). Regenerate with the user's notes until they approve. The sheet is the reference for every later frame, so it has to be right.
|
|
98
|
+
|
|
99
|
+
2. `python <skill>/scripts/gen_images.py projects/<name> --panels` renders every storyboard panel in parallel (each panel is its own image, character sheet as the reference).
|
|
100
|
+
3. Build the **storyboard board**: `python <skill>/scripts/contact_sheet.py projects/<name>`. It lays out every shot with its frames NEXT TO the voiceover line each one has to act out, plus the stamp and panel notes (`storyboard_board.jpg` + `storyboard_board.html`). Show it to the user. This is the last cheap checkpoint: frames cost cents, video costs dollars, so every fix happens HERE.
|
|
101
|
+
|
|
102
|
+
**STOP.** The user approves the frames or names panels to redo (`--panels --only 3.1,7.2` for single panels, `--only 3,7` for whole shots). Run the Director Test on every frame: text or words in the image, a duplicate character, an off-model character, a character who shouldn't be in the frame, the WRONG LOCATION, a panel that doesn't match its line, and BODY MECHANICS (is anyone facing the wrong way for the motion that's coming, like facing down the stairs in a shot where they climb up?).
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## Stage 5: VIDEO
|
|
107
|
+
|
|
108
|
+
Read `reference/05_generation.md` before this stage.
|
|
109
|
+
|
|
110
|
+
1. **Voice:** `python <skill>/scripts/gen_vo.py projects/<name>`. On Kie it voices each line separately (with the neighboring lines as continuity hints) and measures them; on ElevenLabs it does one read with word timestamps. Either way it computes each shot's exact start and end. If Kie's voice service fails and the user has an ElevenLabs key, the script switches the ad to ElevenLabs and asks you to re-run it.
|
|
111
|
+
2. **Cost check.** `python <skill>/scripts/gen_video.py projects/<name> --estimate` prints the clip plan and the estimated cost for Omni and for Seedance.
|
|
112
|
+
|
|
113
|
+
**STOP.** Show the estimate. Default is **Google Omni** (about $8 for a 2-minute ad at 1080p; Seedance 2.5 runs ~$37 at 720p and ~$92 at 1080p for the same length). Recommend Omni for testing; Seedance is the optional upgrade for a proven winner. Wait for the user to choose and say go.
|
|
114
|
+
|
|
115
|
+
3. **Clips:** `python <skill>/scripts/gen_video.py projects/<name> --model omni` (or `--model seedance --resolution 720p`). All clips render in parallel. Every task ID is logged for cost tracking.
|
|
116
|
+
4. **Director Test on every clip:** `python <skill>/scripts/review_clips.py projects/<name>` lays out each clip frame by frame (`review/all_clips.jpg`). Check every shot against the Director Test in `04_storyboard.md`: characters facing the way they move (nobody climbing stairs backwards), real body mechanics, no extra limbs or melting faces, no stray text, right location and costume. Re-render failures (`gen_video.py --only 5`), fixing the panel or beats first if the frame caused it. Tell the user which shots you re-rendered and why.
|
|
117
|
+
5. **Music (optional, recommended):** `python <skill>/scripts/gen_music.py projects/<name>`. Instrumental Suno bed through Kie.
|
|
118
|
+
6. **Assemble:** `python <skill>/scripts/assemble.py projects/<name>`. Fits each clip to its VO window, burns in captions and date stamps, adds the end card, mixes voice and music.
|
|
119
|
+
7. **Report the real cost:** `python <skill>/scripts/cost_report.py projects/<name>`. Pulls `creditsConsumed` for every task from Kie (1 credit = $0.005).
|
|
120
|
+
|
|
121
|
+
Show the final video path, a contact sheet of the finished ad, and the real cost. Ask what they want to change. Fix a bad shot by fixing its panel or beats and re-rendering THAT shot only (`--only 5`), never by patching in the edit.
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## Hard rules (every ad)
|
|
126
|
+
|
|
127
|
+
- **Never invent proof.** No fake results, fake numbers, fake doctors or fake credentials. Dramatized customer stories are fine. Characters with unearned authority are not.
|
|
128
|
+
- **No identity catchphrases** ("There he is", "You look like you again", "feel like yourself again"). Show the identity beat as a scene.
|
|
129
|
+
- **The AI renders ZERO text.** All captions, date stamps and end cards are added in post. Prompts keep screens and papers showing pictures only.
|
|
130
|
+
- **Borrow the moment, never the claim.** When Trigger Hunting from another brand's ad, use its situations and pain points, never its health claims.
|
|
131
|
+
- **Keep claims modest and hedged** ("supports", "a lot of people notice", "starting to"). Big medical claims get flagged to the user, not written.
|
|
132
|
+
- **Stop at every gate.** Money gets spent only after a yes.
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# 00: Hook elements (the highest-leverage part of the ad)
|
|
2
|
+
|
|
3
|
+
Almost every timeline ad opens on one line, and that line is built from a handful of elements. Each element can be described a dozen different ways, and every different description is a new hook to test on the SAME ad body. Your job in Stage 1 is to generate MANY options for each element, then combine them into a big batch of opening lines.
|
|
4
|
+
|
|
5
|
+
The base shape:
|
|
6
|
+
"Here's what happens when [SEGMENT] with [PAIN POINT] [CONSUMPTION VERB] [SOLUTION] for [TIMELINE]."
|
|
7
|
+
|
|
8
|
+
Same product, three very different hooks:
|
|
9
|
+
- "Here's what happens when you take RYZE mushroom coffee for 30 days." (named)
|
|
10
|
+
- "Here's what happens when weed smokers drink this delicious chocolaty latte every morning." (flavor)
|
|
11
|
+
- "Here's what happens when weed smokers chug this weird brown beverage every morning." (blind, curiosity)
|
|
12
|
+
|
|
13
|
+
## Element 1: The segment (WHO, and how you describe them)
|
|
14
|
+
|
|
15
|
+
Pinpoint exactly who the ad talks to, then find several ways to say it. Pull these from the input (sales page, reviews, the winning ad's callouts). Angles to mine:
|
|
16
|
+
- Age + life stage: "women over 45", "new dads", "retirees"
|
|
17
|
+
- Job / daily grind: "nurses on 12-hour shifts", "truck drivers", "teachers"
|
|
18
|
+
- Habit or identity: "weed smokers", "lifelong coffee addicts", "gym rats over 40"
|
|
19
|
+
- Condition, in plain words: "diabetic men", "guys with bad knees"
|
|
20
|
+
- Situation: "moms who haven't slept since the baby", "men who snore so loud their wife moved rooms"
|
|
21
|
+
Give at least 6 segments, each with 2-3 ways to describe it. More specific almost always beats more general.
|
|
22
|
+
|
|
23
|
+
## Element 2: The pain point (and how you describe it)
|
|
24
|
+
|
|
25
|
+
The same pain can be described clinically, physically, emotionally or through a situation:
|
|
26
|
+
- "joint pain" / "creaky knees" / "knees that sound like bubble wrap" / "grabbing the railing on every stair"
|
|
27
|
+
- "low energy" / "the 3pm crash" / "falling asleep on the couch by 8"
|
|
28
|
+
Give 2-3 pain points with 3+ descriptions each. The situational version (a moment you can SEE) is usually strongest.
|
|
29
|
+
|
|
30
|
+
## Element 3: The consumption verb (how they use it)
|
|
31
|
+
|
|
32
|
+
The verb sets the picture and the tone. Match it to the product AND to the energy of the segment:
|
|
33
|
+
- Neutral: takes, drinks, uses, applies
|
|
34
|
+
- Ritual: sips every morning, stirs into their coffee, swallows two before bed, sprinkles on their food
|
|
35
|
+
- Vivid / playful: chugs, slams, pops, rubs on, dabs, gulps
|
|
36
|
+
Give 5+ verbs that fit the product.
|
|
37
|
+
|
|
38
|
+
## Element 4: The solution (named, general, or blind)
|
|
39
|
+
|
|
40
|
+
Three ways to describe the product. Pick per hook; test all three.
|
|
41
|
+
|
|
42
|
+
**Named:** the brand or product name. Best when the brand already has recognition, for retargeting, or when the name itself is curious. "RYZE mushroom coffee", "Aurivita cayenne softgels".
|
|
43
|
+
|
|
44
|
+
**General (category):** the category people already know. Best when the category is trusted and familiar. "mushroom coffee", "a cayenne supplement", "a magnesium drink".
|
|
45
|
+
|
|
46
|
+
**Blind (curiosity):** describe it without naming it, so they have to keep watching to find out what it is. Ways to build a blind characterization:
|
|
47
|
+
- **Color:** "this weird brown beverage", "a red powder", "two little red softgels"
|
|
48
|
+
- **Texture / form:** "a white paste", "a gritty powder", "this thick golden oil"
|
|
49
|
+
- **Flavor:** "a chocolaty latte", "a bitter tea", "a spicy pepper"
|
|
50
|
+
- **Weird or exotic origin:** "a mushroom that grows on dying trees", "a root Japanese monks used", "a resin from the mountains"
|
|
51
|
+
- **Comparison to something familiar:** "a fruit", "a sugar", "a spice already in your kitchen", "a kitchen ingredient", when one of the main ingredients genuinely IS that (only if it's true)
|
|
52
|
+
- **Mystery package:** "a little package", "a weird bottle my sister sent me"
|
|
53
|
+
Give at least 3 named/general options and 6+ blind options. The blind description must be TRUE to the product.
|
|
54
|
+
|
|
55
|
+
## Element 5: The timeline
|
|
56
|
+
|
|
57
|
+
- **In the hook, start short:** 14 or 30 days. A short window feels believable and easy to commit to. (Longer works for slow categories, but default short.)
|
|
58
|
+
- **In the body, let the results keep going.** Even if the hook says 14 or 30 days, carry the milestones out to Month 2 and Month 3, with results that COMPOUND (they keep getting better). See the AOV trick in `03_script_rules.md`.
|
|
59
|
+
Give 3-4 timeline options for the hook (7 days, 14 days, 30 days, 60 days).
|
|
60
|
+
|
|
61
|
+
## Element 6: The opener type
|
|
62
|
+
|
|
63
|
+
The same elements can go through any of the 16 doors in `02_openers.md` (Hypothetical, Testimony, Diary, Situation Open, Two Paths...). Use several.
|
|
64
|
+
|
|
65
|
+
## Stage 1 output: the Hook Bank for this product
|
|
66
|
+
|
|
67
|
+
1. **The element menu:** a table per element with all the options above.
|
|
68
|
+
2. **20+ opening lines** that combine the elements in different ways. Mix named, general and blind solutions, at least 5 opener types, and several segments. Number them. Label each with its opener type and solution mode (named/general/blind).
|
|
69
|
+
3. **Your top 5 picks** and why, by market fit.
|
|
70
|
+
|
|
71
|
+
The user picks one or more lines (or mixes elements). That pick becomes the frame for the script. The other lines are saved to `hooks.md` in the project folder as ready-made hook variations to test on the same ad body later.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# 01: Elements (Trigger Hunting)
|
|
2
|
+
|
|
3
|
+
Every top-spending ad, in ANY format, is proof of what works on its market right now. Trigger Hunting = pulling the proven variables out of a winner (or a brief, or a sales page) and loading them into a timeline ad. The timeline is the container. The input tells you what goes in it.
|
|
4
|
+
|
|
5
|
+
## The 10 variables
|
|
6
|
+
|
|
7
|
+
Extract every one you can find. Quote the market's own words where possible. Leave a variable blank rather than invent it.
|
|
8
|
+
|
|
9
|
+
| Variable | What to look for | Where it goes in the timeline ad |
|
|
10
|
+
|---|---|---|
|
|
11
|
+
| **Segment** | Who it calls out: "men over 50", "diabetic dads", "nurses on night shift" | The frame / hook |
|
|
12
|
+
| **Situation** | ONE specific moment where the problem fires: a place, a time, an object, often someone else watching | The opener |
|
|
13
|
+
| **Pain points** | Symptoms and frustrations, in their words | The before-state and Day 1 |
|
|
14
|
+
| **Objections** | What stops them buying: "I've tried everything", "it's just my age", "it's in my head" | The skeptic beat, and one way to mine milestones |
|
|
15
|
+
| **Wrong suspect + real villain** | What they blame vs. what's actually causing it | The real-cause beat ("It was never his age. It was...") |
|
|
16
|
+
| **Failed fixes** | What they already tried | After the timeline, or built into it (Head-to-Head, Two Paths) |
|
|
17
|
+
| **Desired outcome** | The result they crave, in their words | The top of the milestone ladder |
|
|
18
|
+
| **Witness** | Who notices: spouse, kid, coworker, doctor | The social-observation milestone |
|
|
19
|
+
| **Identity payoff** | Who they get to be again, how they're seen | The final scene |
|
|
20
|
+
| **Mechanism picture** | The one simple image that explains why it works ("Sugar chokes the little pipes. Cayenne helps keep them flowing.") | Ingredient credits inside the timeline, or the explanation after it |
|
|
21
|
+
|
|
22
|
+
## What makes a killer SITUATION
|
|
23
|
+
|
|
24
|
+
A situation beats a symptom every time. "Cold feet" is a symptom. "His wife yelps and pulls away in bed, and now she sleeps on the far edge" is a situation. A strong one has most of:
|
|
25
|
+
- **A body in the room:** a real person, a real place, a real time.
|
|
26
|
+
- **A physical detail you can SEE:** an object, a sound, a sensation.
|
|
27
|
+
- **Somebody else it hurts:** a partner, a kid, a coworker.
|
|
28
|
+
- **A cost bigger than the symptom:** what they're really losing.
|
|
29
|
+
|
|
30
|
+
## Reading each input type
|
|
31
|
+
|
|
32
|
+
**Brief:** pull what's given, then ASK the user for the missing high-value variables (especially the situation, the witness and the failed fixes). Offer 3 guesses for each so they can just pick.
|
|
33
|
+
|
|
34
|
+
**Sales page:** sales pages are packed with variables. The headline and lead usually hold the segment and outcome. The "story" section holds situations and the wrong suspect. The FAQ holds objections. The mechanism section holds the villain and the mechanism picture. Testimonials hold witnesses and identity payoffs, in real customer words.
|
|
35
|
+
|
|
36
|
+
**Transcript of another winning ad (any format):** this is the best input. Pull the situation, the pain points and the witness word for word. Note which variables the ad leans on hardest; that's likely why it's spending. **Borrow the moment, never the claim:** situations and pain points transfer to the user's product; another brand's health claims and mechanism do not.
|
|
37
|
+
|
|
38
|
+
## Milestones come from two places
|
|
39
|
+
|
|
40
|
+
1. **What they WANT:** outcomes and benefits. Climb them in ladder order.
|
|
41
|
+
2. **What stops them:** objections. List them in the order they'd hit the prospect and give each one the milestone where it dies:
|
|
42
|
+
|
|
43
|
+
| Objection | Milestone that kills it |
|
|
44
|
+
|---|---|
|
|
45
|
+
| "I've tried stuff like this, nothing works" | Day 1 / Week 1 skeptic beat: agree with them first ("Week one, nothing.") |
|
|
46
|
+
| "It's probably in my head" | A small BEHAVIOR win they can't argue with |
|
|
47
|
+
| "It won't fix the thing I actually care about" | The visible win inside the exact situation they hate |
|
|
48
|
+
| "Nobody will notice anyway" | The witness |
|
|
49
|
+
| "Why would this work when everything else failed?" | After the timeline: real cause, failed fixes, mechanism picture |
|
|
50
|
+
|
|
51
|
+
## Output of this stage
|
|
52
|
+
|
|
53
|
+
Write the variables into `project.json` under `elements` as plain strings. Then build the hook element menu and the 20+ opening lines (see `00_hook_elements.md`).
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# 02: Openers
|
|
2
|
+
|
|
3
|
+
"Here's what happens when..." is ONE door. The milestones, ladder, mechanism and close underneath never change. The opener decides WHO tells it, in what tense, with what emotional license. Swapping only the opener is the cheapest test there is: RYZE ran the same 290-word body behind a Testimony opener and a Hypothetical opener.
|
|
4
|
+
|
|
5
|
+
Slots: [AVATAR] [PAIN] [PRODUCT] [WHO/AUTHORITY] [RITUAL] [TIMELINE] [OTHER]. Fill them with the variables from Stage 1. Be SPECIFIC: "two [PRODUCT] softgels before every shift" beats "a pill"; "a nurse on the emergency floor for 12 years" beats "a nurse".
|
|
6
|
+
|
|
7
|
+
The example lines below use one made-up product (a turmeric joint softgel) so you can see the opener change while the body holds. Real "in the wild" lines are quoted as they ran.
|
|
8
|
+
|
|
9
|
+
## The 16 openers
|
|
10
|
+
|
|
11
|
+
**1. Hypothetical.** "This is what WOULD happen to [AVATAR] with [PAIN] if he [RITUAL] for [TIMELINE]."
|
|
12
|
+
In the wild (RYZE): "This is what would happen to a burnt-out blue-collar dad if he replaced his energy drinks."
|
|
13
|
+
Why: future-pacing with deniability; a what-if makes no promise. Use: cold traffic, no real customer story.
|
|
14
|
+
|
|
15
|
+
**2. Testimony.** "A [AVATAR] [swapped X for RITUAL] for [TIMELINE]. Here's what happened."
|
|
16
|
+
In the wild (RYZE): "A construction worker replaced his energy drinks with mushroom coffee for 30 days. Here's what happened."
|
|
17
|
+
Why: reads like a report of something that already happened. Use: a real or representative case.
|
|
18
|
+
|
|
19
|
+
**3. Diary.** "I've been [WHO/AUTHORITY]. [PAIN]. Here's what happened once I started [RITUAL]."
|
|
20
|
+
Example: "I've been a nurse on the emergency floor for 12 years. By the end of every shift, my knees were screaming. Here's what happened once I started taking two [PRODUCT] softgels before every shift."
|
|
21
|
+
Why: first person, one voice; the WHO doubles as authority. Use: emotional payoffs.
|
|
22
|
+
|
|
23
|
+
**4. Skeptic.** "I bought [PRODUCT] to EXPOSE it. [Every X I tried did nothing], so I documented [TIMELINE] to prove it."
|
|
24
|
+
In the wild (Resilia): "I bought Resilia to expose it. I set up a camera and documented 30 days to prove it does nothing."
|
|
25
|
+
Why: the narrator IS the objection; every milestone is a grudging concession. Use: jaded markets.
|
|
26
|
+
|
|
27
|
+
**5. Bro / Yapper Friend.** "What happens if [your buddy who PAIN] actually [RITUAL] every day?"
|
|
28
|
+
In the wild (Resilia): "What happens if your bro actually takes oregano oil every day? Day 1, nothing happens. He calls you to say it's a scam. Classic bro."
|
|
29
|
+
Why: comedy; the skeptic beat lands on a character they laugh at. Use: younger or male audiences.
|
|
30
|
+
|
|
31
|
+
**6. Witness.** "Here's what happened when [OTHER: my dad], who [PAIN], finally [RITUAL]."
|
|
32
|
+
Tell it in the PAST tense; the narrator watched it already happen.
|
|
33
|
+
Why: the narrator IS the witness. Use: gift buyers, spouses, adult kids buying for parents.
|
|
34
|
+
|
|
35
|
+
**7. False Warning.** "If you [PAIN/TRAIT], be careful taking [PRODUCT]. Because here's what could happen..."
|
|
36
|
+
In the wild (RYZE): "If you smoke weed, you gotta be super careful if you drink RYZE. Because here's what could happen."
|
|
37
|
+
Why: framed as a downside, the desire can be stated far more vividly. Use: wants they'd never admit out loud.
|
|
38
|
+
|
|
39
|
+
**8. Talking Problem.** "I'm [PAIN, personified]. Here's what happens to me when you start [RITUAL]."
|
|
40
|
+
In the wild (RYZE): "I'm a 42 year old mom bod. This is what happens to me after drinking one cup every day. Day one, I don't feel shit."
|
|
41
|
+
Why: the problem narrates its own retirement. Use: embarrassing problems.
|
|
42
|
+
|
|
43
|
+
**9. Harm Ladder.** "This is what might happen if you keep [ignoring PAIN] for too long. After [Year 1]... by [Year 3]..."
|
|
44
|
+
In the wild (RYZE): "This is what might happen to a man if he smoked weed every single night for too long. After 12 months... by year 3... by year 5..."
|
|
45
|
+
Why: damage climbs, then a concession, then the pivot to the product. Use: habits they won't quit, compliance-sensitive products.
|
|
46
|
+
|
|
47
|
+
**10. Two Paths.** "Two [PRODUCTS]. One of them you'll take for [TIMELINE] while [PAIN keeps going]. Pick."
|
|
48
|
+
In the wild (Resilia): "Two oregano oil supplements. One of them you'll take every day for eight months while the parasites keep multiplying. Pick."
|
|
49
|
+
Why: the failed fix gets the harm ladder, yours gets the recovery ladder. Use: they tried the cheap version and quit.
|
|
50
|
+
|
|
51
|
+
**11. Conditional Ladder.** "If you take [PRODUCT] for just [one week], you might notice... If you take it for [two weeks]..."
|
|
52
|
+
Why: pure benefit ladder, no avatar. Use: retargeting, product-aware, lapsed buyers.
|
|
53
|
+
|
|
54
|
+
**12. Situation Open.** "[NAME]'s [SITUATION] every [WHEN]. [WHO ELSE IT HURTS]. Then [PRODUCT] showed up."
|
|
55
|
+
In the wild (Aurivita): "Frank's feet were ice cold in bed every night. She'd yelp and pull away... Then a little package showed up."
|
|
56
|
+
Full structure: situation -> product arrives (blind is spicier) -> short timeline (tiny win, self-observation, witness) -> real cause ("It was never his age") -> failed fixes -> reveal + mechanism picture -> ritual + safety net -> offer.
|
|
57
|
+
|
|
58
|
+
**13. Head-to-Head.** "Two [AVATARS] got [the same bad news]. One took [the usual fix]. One took [PRODUCT]." Then week by week, side by side.
|
|
59
|
+
Why: the failed fix is built INTO the timeline. Use: a popular "usual fix" you beat.
|
|
60
|
+
|
|
61
|
+
**14. Spiral, Then Rescue.** "POV: you're [AGE] and [the scary moment]." Days get WORSE, then the product, then they get better.
|
|
62
|
+
Why: a negative and a positive timeline in one ad. Use: problems that get scarier when ignored.
|
|
63
|
+
|
|
64
|
+
**15. Ingredient Experiment.** "What would happen if you [ate the raw ingredient] every day for [TIMELINE]?" Then the product gets the same result without the downside.
|
|
65
|
+
Why: curiosity about a kitchen ingredient they already trust. Use: the hero ingredient is a familiar food or spice.
|
|
66
|
+
|
|
67
|
+
**16. "Don't Buy".** "Don't buy [PRODUCT] if [you like having an excuse to PAIN]."
|
|
68
|
+
In the wild (RYZE, 149 days running): "Do not buy RYZE Mushroom Coffee."
|
|
69
|
+
Why: sounds like it works against the sale, so they need to know why.
|
|
70
|
+
|
|
71
|
+
## The Borrowed Open
|
|
72
|
+
|
|
73
|
+
The opener can come from ANY winning ad in any format. Take a proven situation, frustration or micro-moment, add ONE bridge line, then hit Day 1 fast. Benchmark: RYZE's #12-ranked timeline ad says "Day one" 53 words in.
|
|
74
|
+
|
|
75
|
+
Bridge lines:
|
|
76
|
+
- "That was me. Until my [PERSON] handed me [PRODUCT]. Day one..."
|
|
77
|
+
- "So I tried one thing for 30 days. Here's what happened."
|
|
78
|
+
- "Then she started [RITUAL]. Week one..."
|
|
79
|
+
- "Here's what changed when I stopped [FAILED FIX] and started [RITUAL]."
|
|
80
|
+
|
|
81
|
+
## Using the openers in Stage 1
|
|
82
|
+
|
|
83
|
+
Combine the openers with the element menu from `00_hook_elements.md` to write the 20+ opening lines. Use at least 5 different opener types, and mix named, general and blind descriptions of the solution.
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# 03: Script rules
|
|
2
|
+
|
|
3
|
+
## Why timeline ads work (keep this in mind while writing)
|
|
4
|
+
|
|
5
|
+
- **Imagined ownership:** the prospect pictures USING the product as a daily ritual and feeling the payoff. They're remembering a routine they haven't started. That's Cialdini's Consistency principle, weaponized: buying becomes staying consistent with the version of themselves they already watched.
|
|
6
|
+
- **They're a witness, not a judge:** the claims don't feel like claims because the viewer watches them happen.
|
|
7
|
+
- **Gradualization:** start with almost-nothing claims and climb. Every checkpoint earns permission for a bigger promise.
|
|
8
|
+
- **The skeptic beat buys trust:** saying "nothing happened on Day 1" validates their inner skeptic. 38% of winning ads do it.
|
|
9
|
+
- **A timeline is a serial:** every checkpoint opens a new loop and ends on momentum.
|
|
10
|
+
|
|
11
|
+
## The milestone ladder (order matters)
|
|
12
|
+
|
|
13
|
+
Data from 277 winning positive timeline ads (RYZE, IM8, Resilia). Average position where each benefit first appears, 0 = first word after the hook, 1 = the moment the ad starts selling:
|
|
14
|
+
|
|
15
|
+
gut 0.35 / cravings 0.37 / felt bloat 0.39 / focus 0.40 / energy 0.40 / clothes fit 0.43 / visible face or body 0.44 / sleep 0.45 / other people notice 0.47 / identity 0.80 / a weight or lab number 0.80
|
|
16
|
+
|
|
17
|
+
So climb:
|
|
18
|
+
1. **Skeptic beat / invisible changes.** Nothing felt, or work happening where they can't feel it. (64% of winners open Day 1 on "nothing" or invisible work. Only claim a felt Day 1 win in categories where fast is already believable: cravings, calm, hydration.)
|
|
19
|
+
2. **A small, tangible win tied to a real moment in their day.** "You weren't buzzing, but you felt steady... by noon you realized you were still on your first cup of coffee."
|
|
20
|
+
3. **Self-observation (behavior).** Something they DID or STOPPED doing. They can't doubt their own behavior.
|
|
21
|
+
4. **Visible wins + social observation, together, mid-ad.** Belt notch, jeans buttoning, the mirror, and right on their heels, someone else notices (kills the "placebo" doubt).
|
|
22
|
+
5. **Big numbers (if any) and identity, at the END.** The scale, the lab result, the doctor's chart. Then the identity/lifestyle scene. Many winners skip the number entirely.
|
|
23
|
+
|
|
24
|
+
**The AOV trick (results that compound):** the hook can say 14 or 30 days, but carry the milestones out to Month 2 and Month 3, and make each one BUILD on the last ("by month two, it's not just the stairs..." / "month three is when the people around you start asking"). If the best results land after the first bottle runs out, the viewer wants the 3-bottle bundle, not the single. Tie the offer to it: "Most people grab the 3-month supply, because month three is where it really comes together." Only use offer details the user gives you.
|
|
25
|
+
|
|
26
|
+
Spacing: DENSE early (Day 1, 3, 5, 7), sparse late (14, 30). Most winners run 3-7 milestones; 4 is the most common. Each checkpoint ends on momentum ("then things got interesting"), never a plateau.
|
|
27
|
+
|
|
28
|
+
## Two mechanism layers
|
|
29
|
+
|
|
30
|
+
- **Layer 1, ingredient credit:** a short tag naming what's doing the work, attached to something happening TO the person. "Turkey tail feeds the good bacteria in your gut. The bloat settles." 74% of winners put this INSIDE the milestones.
|
|
31
|
+
- **Layer 2, full explanation:** what was really wrong, why other fixes failed, why this product fixes it. Only 16% of winners do this inside a milestone. Most put it in the hook, on Day 1, or AFTER the timeline.
|
|
32
|
+
|
|
33
|
+
Pick one structure and say which:
|
|
34
|
+
- **Option 1, embedded:** Layer 1 credits in the milestones, Layer 2 after.
|
|
35
|
+
- **Option 2, results first:** milestones are pure results, then the full explanation after (Aurivita's cold-feet ad).
|
|
36
|
+
|
|
37
|
+
Never let it sound like the brand lecturing mid-timeline.
|
|
38
|
+
|
|
39
|
+
## Beat order (default)
|
|
40
|
+
|
|
41
|
+
0. Frame + tease (who, the ritual, the timeline; optionally name the last stage as the prize)
|
|
42
|
+
1. Day 1 (taste/ease, skeptic beat)
|
|
43
|
+
2. Small wins (often framed as things that STOP)
|
|
44
|
+
3. Feelings (+ ingredient credits if Option 1)
|
|
45
|
+
4. Visible + social
|
|
46
|
+
5. Identity / life scene
|
|
47
|
+
6. Bridge + differentiator (the villain is the cheap knockoff or the wrong fix, never the viewer)
|
|
48
|
+
7. The seal (one line that locks the ritual: "One cup every morning.")
|
|
49
|
+
8. Proof (only REAL proof the user gives you)
|
|
50
|
+
9. Offer + guarantee + urgency (only what the user gives you)
|
|
51
|
+
|
|
52
|
+
The timeline is ~75% of the script. The sale is the last quarter.
|
|
53
|
+
|
|
54
|
+
## Line craft
|
|
55
|
+
|
|
56
|
+
- One spoken line per line. Write for the ear. Median 7-9 words.
|
|
57
|
+
- Micro-moments from THEIR real day (the 3pm crash, the snooze button, the stairs).
|
|
58
|
+
- The pronoun trick: third-person frame, then slide into "you" for the body.
|
|
59
|
+
- Name the ritual in the tense they'd use once they own it: "two softgels with breakfast."
|
|
60
|
+
- Hedge the claims: "starting to", "a lot of people notice", "might".
|
|
61
|
+
- **Pronunciation check:** list every product/industry word a voice could misread (softgels, CoQ10, ashwagandha, brand names) in `project.json` -> `pronounce` with a phonetic spelling, e.g. `"softgels": "soft jells"`, `"CoQ10": "co Q ten"`. The voice says the spelling; captions still show the real word.
|
|
62
|
+
- Numbers in the script are written as they should be SPOKEN ("thirty days", "twelve-hour shift") so the voice reads them right.
|
|
63
|
+
|
|
64
|
+
## Banned
|
|
65
|
+
|
|
66
|
+
- Identity catchphrases: "There he is", "There she is", "You look like you again", "feel like yourself again". Show the scene instead (his wife reaches for his hand on the couch; he's on the floor building Legos with his grandson).
|
|
67
|
+
- AI tells: "here's the kicker", "here's the thing", "it's not X, it's Y" balanced flips, "game-changer", "unlock", "elevate", recap tags ("that's the whole game").
|
|
68
|
+
- Em-dashes (use a period, a comma or "...").
|
|
69
|
+
- Invented proof: fake results, fake reviews, fake doctors or credentials, user counts the user didn't give you.
|
|
70
|
+
- Big medical claims (cures, reverses, replaces medication). Flag them to the user instead.
|
|
71
|
+
|
|
72
|
+
## Self-check (run before showing the script; list results)
|
|
73
|
+
|
|
74
|
+
1. Does Day 1 promise almost nothing (or only a believable fast win)?
|
|
75
|
+
2. Do the milestones climb in ladder order, with identity and any number at the end?
|
|
76
|
+
3. Is every milestone a specific MOMENT, not a benefit word?
|
|
77
|
+
4. Is there a witness?
|
|
78
|
+
5. Is the mechanism placed per Option 1 or 2, and never as a mid-timeline lecture?
|
|
79
|
+
6. Is every claim hedged and supported by the user's inputs?
|
|
80
|
+
7. Any banned phrase, catchphrase, em-dash or invented proof? (must be zero)
|
|
81
|
+
8. Do the results keep going past the hook's timeline into Month 2 and Month 3 (the AOV trick)?
|
|
82
|
+
9. Every tricky product word has a `pronounce` entry?
|
|
83
|
+
10. Word count and estimated runtime (words / 2.6 = seconds, roughly).
|