Starting a New Workflow¶

End-to-end walkthrough: how to take a product brief and produce a finished workflow ready for fan-out. This is the path you'll follow most often.

flowchart TB
    A[1. Gather the brief] --> B[2. Confirm direction]
    B --> C[3. Script via Script Writer]
    C --> D{Approved?}
    D -->|no| C
    D -->|yes| E[4. Storyboard via Visual Planner]
    E --> F{Approved?}
    F -->|no| E
    F -->|yes| G[5. Generate .nbflow<br/>via PatchWork Importer]
    G --> H[6. Run Generation Runner]
    H --> I[7. Review in PatchWork]
    I --> J{Pass?}
    J -->|no, iterate| K[Bump V0-N, fix, regenerate]
    K --> H
    J -->|yes| L[8. Fan out to other accounts]
    L --> M[V1 - approved]

1. Gather the brief¶

Ask the user (or client) these questions. You can move on with incomplete answers — the Visual Planner will fill gaps — but the more concrete the brief, the less iteration later.

Product¶

What brand and SKU?
Key ingredients, mechanism, primary benefit
Any existing brand docs you should load

Audience¶

Age range, gender, lifestyle
Awareness level (Most Aware → Unaware on the Schwartz scale)
Pain points you're addressing

Tone¶

Aspirational / relatable / edgy / warm / clinical / casual
Energy level (calm explainer vs urgent hook)

Platform¶

TikTok, Reels, Facebook, or all three
Defaults to TikTok if unspecified

Sales channel¶

TikTok Shop — Shop button on video. AI Label Trick recommended.
Amazon (via keyword) — Comment keyword triggers ManyChat DM with link. No AI label.
Meta Shop (FB/IG) — Shop button on Reel → Amazon link. No AI label.

This decides the CTA wording and whether you need the AI Label Trick.

Content type¶

Defaults to sales (product-focused, conversion goal). Optionally growth (educational, soft sell — recipes, anatomy explainers). Only ask if the user brings it up; default is fine.

B-roll density¶

High — B-roll every speaking scene
Medium (default) — B-roll at scenes that can be visually reinforced
Low — 2-3 critical moments only
None — continuous speaking, no cutaways

For a video-copy workflow, B-roll density is dictated by the source video, not picked freely. See Video Copy Workflow.

Visual direction¶

Ask these — the user can skip any, and the Visual Planner will fill gaps:

Model / subject look — gender, age range, grooming, wardrobe vibe (streetwear / athleisure / polished / cozy)
Environment — indoor / outdoor, specific setting (bathroom vanity, kitchen counter, gym, bedroom, car), time of day
Lighting preference — natural window light, ring light, overhead LED, harsh flash, golden hour
Camera style — selfie, tripod, handheld, propped-on-surface, mirror shot
Color palette — warm / cool / neutral, dominant tones
Aesthetic vibe — raw UGC / semi-polished / lo-fi retro / clean minimal / maximalist cluttered
Production level — authentic smartphone feel vs semi-professional

Creative template (if applicable)¶

If the user provides a creative template from the Researcher (a viral video they want to copy or a documented format), extract the visual direction directly from the template instead of asking each question individually. Map:

Template section	Maps to
Person (age, gender, look, wardrobe)	Model / subject look
Environment (setting, lighting, props, background)	Environment + Lighting preference
Dominant Style + Lens Feel + Camera Quality	Camera style + Production level
Color Palette + Vibe	Color palette + Aesthetic vibe
Production Level	Production level

2. Confirm direction¶

Summarize the brief back to the user — including visual direction — for confirmation. This is your last chance to catch a misunderstanding cheaply. Once the user says "go," scripting starts.

A good confirmation summary looks like:

Building a sales workflow for Brand XYZ, targeting menopausal women 45-60, using Account A as the test avatar. Tone is warm and conversational. Platform: TikTok Shop with AI Label Trick. B-roll density: Medium. Setting: bright kitchen, natural window light, raw UGC aesthetic. Ready to start scripting?

3. Script via Script Writer¶

Once your brief is confirmed, ask Claude to write the script. Behind the scenes, the Script Writer agent takes:

The product brief (everything from step 1)
Target audience
Pattern / framework preferences (if any)
The Schwartz awareness level
Compliance constraints (banned words, approved angles)

The Script Writer returns a script — typically a hook + body + CTA structure.

Present the script to the user for approval. If they request changes:

Small tweaks (a line here or there): edit directly, no need to ask again
Direction changes (different hook angle, different CTA approach): ask again to Script Writer with updated brief

When the user approves the script, you're cleared to move to storyboarding.

4. Storyboard via Visual Planner¶

Once the script is approved, ask Claude to build the storyboard. The Visual Planner takes:

The full approved script text (always pass the whole script — the Visual Planner needs it for scene segmentation and word-count-per-scene planning)
Visual direction from step 1
B-roll density selection
Product info
Target audience
Sales channel
Any Researcher creative template
Avatar info (account, archetype)
Prehook plan (if applicable)

The Visual Planner returns two artifacts:

User summary: 1-2 sentences per scene. Present this to the user for approval.
Internal detail: Full scene specifications — composition, camera angle, lighting, subject pose, props. Used when delegating to the Image Prompter and Veo Prompter in step 5.

When the user approves the storyboard (the Video Plan — script + storyboard together), Stage 5 runs automatically. No more per-step approval until generation completes.

5. Generate the `.nbflow` file¶

Automatic — no separate approval needed. The Manager orchestrates:

Image prompts — handled by the Image Prompter. One prompt per shared reference image group for speaking scenes. B-roll gets one reference image per clip (not start+end pairs).
Speaking video prompts — handled by the Veo Prompter. Uses the universal talking head template; only the dialogue line changes per scene.
B-roll video prompts — handled by the Veo Prompter. Natural language, no dialogue, ambient audio only.

Note: B-roll prompts run manually, not inside the .nbflow. They're saved as standalone files in Assets/{workflow}/broll/ and executed via manual NanoBanana / Veo calls.
The .nbflow itself — delegated to the PatchWork Importer. Wires up image gens → scene Veo3 nodes → Approval gates.
Save outputs — .nbflow lands in projects/{month}/{brand}/{growth|sales}/testing/{workflow}-V0-1.nbflow. (First testing version is V0-1.)
Reference material checklist — listed for the user (avatar photo, product photo, etc.).

Before generation, run the pre-generation sanity check. If it surfaces issues, fix them before moving on.

6. Run the Generation Runner¶

Ask Claude to run generation. The Generation Runner with:

The .nbflow path
G-Labs tunnel URL (auto-started by the Manager if not provided)
API key
Reference image path (if avatar refs are unwired)
Concurrency (3 default, 5 cap)

The runner:

Enforces outputCount=4 on every gen node
Uploads reference images to R2
Wipes stale cache
Runs all generation nodes
Visually reviews every image for AI tells, auto-reruns flagged outputs (up to 3 attempts)
Exports -generated.nbflow to projects/{month}/{brand}/Generations/

For a fast image-only validation pass (skip video gen), pass mode=images. Useful when you want to verify image gens look right before committing the full Veo budget.

7. Review in PatchWork¶

Open the exported -generated.nbflow in PatchWork's web UI. Each generation node shows 4 candidates in its Approval gallery.

For each scene:

Pick the strongest still from the image gen Approval
Pick the strongest video clip from the Veo3 Approval
If no candidate is acceptable — rerun that node:
- Same prompt, different seed (re-roll)
- OR edit the prompt and rerun (if the issue is a prompt problem, not a model variance problem)

PatchWork remembers your picks. You can come back later and finish reviewing without losing state.

8. Iteration during testing (V0-N)¶

Once you're reviewing, every meaningful change bumps the V0-N counter and archives the previous version. See Variants & Versioning — what counts as a meaningful change.

Typical iteration sequence on the test account:

V0-1 → first build
V0-2 → fix prompts that produced bad outputs, regenerate
V0-3 → adjust storyboard, regenerate
V0-4 → maybe one more QA pass on stubborn scenes

Bump the version every time — don't overwrite. The previous file moves to backups/{workflow}-V0-N.nbflow.bak-{date}-{reason}. This gives you a frozen audit trail to diff against if something later breaks.

Iterate until the user is happy with the test account's outputs.

9. Fan out to other accounts¶

When the test account is clean, fan out to the remaining target accounts. Follow the Fan-out Protocol — 7 steps in order:

Duplicate the workflow tab per target account
Reassign node IDs so every node is globally unique
Rename nodes to match each avatar
Swap the avatar character reference sheet
Walk the per-avatar CUSTOMIZED checklist (wardrobe, persona, dialogue swaps)
Verify STANDARD items are byte-identical across tabs
Run a single test generation per tab to sanity-check the avatar swap

The fan-out itself bumps the version (V0-N → V0-N+1 — fan-out is still part of testing).

10. Graduate to V1¶

When all account tabs ship clean AND the user explicitly approves the workflow → graduate to V1. Move the file from testing/ to approved/. Update the version registry.

The workflow is now production-ready. Any further changes follow the variant rules.

Common first-workflow mistakes¶

Skipping the brief confirmation step: You'll write a script for what you think the user wants, then spend two rounds rewriting it. The confirmation step is 2 minutes; misalignment costs an hour.
Asking the user every visual direction question individually: If they don't know, propose defaults and let them push back. Decision fatigue at the brief stage kills momentum.
Generating before running the sanity check: You'll discover the model field was wrong AFTER paying for a Generation Runner pass. Always run the sanity check first.
Iterating in place without bumping V0-N: You lose the audit trail. Even a "small" change to a prompt deserves a version bump.
Fanning out before the test account is truly clean: Drift gets multiplied across N accounts. Fix the test account first, fan out once.
Treating the AI tells QA as optional: The Generation Runner does this automatically. If you skip it (e.g. by running a manual generation outside the runner), shipped content has avoidable hand/face artifacts.