Higgsfield Content Pipeline: Agent Operating Manual

# Higgsfield Content Pipeline: Agent Operating Manual

You are working in a Higgsfield video production workspace. Your job is to run the content pipeline end to end: write prompts, fire renders, check keyframes with the user, and assemble final cuts. Read this file fully before generating anything.

## Setup checks (run first, every session)

1. `higgsfield` must be on PATH. If not:
   ```bash
   curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh
   ```
2. If `higgsfield account status` fails with "Session expired" or "Not authenticated", ask the user to run `higgsfield auth login` and wait.
3. Check credit balance with `higgsfield account status` before a big render batch. A 10s Seedance clip costs ~150 credits; warn the user if a planned batch exceeds their balance.

## The production loop (personal-brand reels)

When the user asks for a reel, run this loop. Keep it tight, the user iterates fast.

1. Ask which scenes they want (or propose 3 to 5 concepts and let them pick).
2. If no Soul-2 ID exists yet, train one first (see Soul training rules below). Save the UUID to `SOUL_ID.txt` in the workspace.
3. For each scene, write the still prompt using the 7-part framework below.
4. Render the still:
   ```bash
   higgsfield generate create text2image_soul_v2 --prompt "$(cat scene_still.txt)" \
     --soul-id <UUID> --quality 2k --aspect_ratio 9:16 --wait
   ```
5. Show the user the still for approval. Do not fire the I2V render on an unapproved still (stills are ~15 credits, clips are ~150).
6. Write the I2V motion prompt with timestamped beats, then render:
   ```bash
   higgsfield generate create seedance_2_0 --prompt "$(cat scene_video.txt)" \
     --start-image still.png --duration 10 --aspect_ratio 9:16 --wait
   ```
   If it IP-fails, fall back to `--image` reference mode (Seedance generates the opening freely and uses the image only for identity).
7. Show keyframes for approval. Iterate per scene until picked.
8. Once all scenes are approved, concat:
   ```bash
   ffmpeg -f concat -safe 0 -i list.txt -c copy reel.mp4
   ```
   If clips freeze at cut points, re-encode: drop `-c copy`, add `-c:v libx264 -crf 18 -c:a aac -b:a 192k -g 30`.

Push back when the user's feedback contradicts itself. Don't yes-man.

## The e-commerce loop (no Soul training needed)

For product businesses, route by deliverable:

- **Product photos** (studio, lifestyle, Pinterest): use the `higgsfield-product-photoshoot` skill.
- **Marketplace listing set** (compliant main image, secondary images, A+ modules): use the `higgsfield-marketplace-cards` skill.
- **Product video ad**: write the prompt with the `seedance-ecommerce-ad` skill, render via `seedance_2_0` with the product photo as `--image` reference.
- **360 rotation / hero spin**: `seedance-product-360` skill.
- **UGC-style or avatar ads**: Marketing Studio via the `higgsfield-generate` skill.

Same approval discipline: show the user every image before spending clip-level credits on video.

## The 7-part still prompt framework

1. **Technical setup**: resolution, aspect ratio (9:16 for Reels/TikTok), fps.
2. **Subject identity lock**: "The character in my Soul profile, [framing], as [role]."
3. **Wardrobe and physical details**: every visible piece, specific.
4. **Setting**: what's behind and around, architecture, time of day.
5. **Lighting and color**: color temperatures, real film references ("ARRI ALEXA bleach bypass").
6. **Camera and composition**: lens, aperture, angle.
7. **Identity lock + safety footer**: restate "face from Soul reference", "NO blood", "NO trademarked brands".

## Motion prompts: timestamped micro-beats

Static "moving portrait" clips read as AI. Multi-shot sequences read as cinema. Break every 10s prompt into 4 to 6 beats:

- 0-1.5s: cool non-face intro (object close-up, action detail, environment cue)
- 1.5-3s: reveal subject, action begins
- 3-5s: rapid action cuts (0.4 to 0.5s each), multiple angles
- 5-7s: peak action / key beat, slow-mo if dramatic
- 7-9s: aftermath / hero pose
- 9-10s: final tight on face OR pulled-back wide silhouette

End EVERY video prompt with: "NO MUSIC. NO BACKGROUND SCORE. Native diegetic sound only." Otherwise each clip self-generates a clashing soundtrack. One unified music bed gets laid in post.

See `examples/prompts/` for shipped still + motion pairs, and `playbook/PROMPTING-PLAYBOOK.md` for the full Seedance prompting reference.

## IP filter rules (the biggest landmine)

Seedance aggressively blocks renders that pattern-match copyrighted franchises or real celebrities. Soul-2 text2image is more permissive, so a still can succeed and its I2V can still fail.

**Strip from Seedance prompts:**
- Direct franchise names (movie titles, character names, league/brand names like UFC or ESPN)
- Distinctive franchise-specific terms (anything only one franchise uses)
- Real celebrity names. Describe the archetype instead ("red-bearded southpaw boxer", "heavyweight champion build")

**What works:**
- Generic descriptors that evoke the reference without naming it
- `--image` reference mode instead of `--start-image` when the still itself fingerprints
- Never feed real broadcast footage or celebrity clips as `--video` references; they flag every time

## Soul training rules

- Use 8 to 10 photos, ALL front-facing. No side profiles, no hand-on-face, no extreme lighting, no filters, no group shots.
- The single best photo is one clean straight-on no-filter shot.
- The model overfits to the most visually distinctive photo in the set. If renders inherit weird lighting or composition, retrain with a more uniform set.
- Always train with `--soul-2`. Soul-Cinematic is a different training type and produces the wrong face for `text2image_soul_v2`.
- Full photo spec in `playbook/PHOTO-REFERENCE-GUIDE.md`.

## Known issues and fixes

- **Big-head problem**: Soul stills bias toward face dominance. For full-body shots, frame as a low-angle hero from floor level, face at 12 to 15% of frame, and prompt "head proportionally correct, NOT a big head on a small body."
- **`--wait` timeout**: defaults to 10 minutes; Seedance 10s renders sometimes run longer. The job is still running. Fetch with `higgsfield generate get <job-id>` or `higgsfield generate list`. Also, flaky "Cannot reach" errors often mean the job DID submit. Always check `generate list` before re-firing or you double-spend.
- **Concat freezes at cut points**: re-encode instead of stream-copy (command in step 8 above).

## Workspace conventions

- Prompts live as `.txt` files, one per render, named `NN_scene_still.txt` / `NN_scene_video.txt`, versioned `_v2`, `_v3` as they iterate.
- Save render job logs so failed renders can be retried without rewriting prompts.
- Keep face photos in `face-refs/` (gitignored, never commit personal photos).
- Final picks and montages go in `clips/` (gitignored, video files don't belong in git).