@officexapp/vidfarm-devcli 0.21.24 → 0.21.27

package/dist/src/services/sequence-prompts.js

@@ -0,0 +1,463 @@
+// ── Storyboard-driven AI sequence grammar ───────────────────────────────────
+// The prompt architecture behind the "character card → storyboard sheet →
+// Seedance/AI-video" workflow. This module is PURE (no I/O, no network): it
+// turns a `sequence.json` plan into the three prompt strings the pipeline
+// needs, so `vidfarm sequence` stays a thin orchestrator and the grammar has a
+// single source of truth (also reused by docs + the local-agent task file).
+//
+// The grammar is distilled from the workflows that actually ship this look in
+// public (aimikoda's THE WIND CALLS / Mei Lin boards, insMind's 9-grid
+// commercial board, the ViralOps "board first, then burn credits" rule):
+//
+//   1. CHARACTER CARD  — one identity sheet per character. Locks face, body,
+//      wardrobe and art style. Never regenerated once approved.
+//   2. STORYBOARD SHEET — one grid image per part, written with an explicit
+//      block grammar ([SCENE PACKET], [IDENTITY CONSISTENCY], [SPATIAL
+//      CONTINUITY LOCK], [DIRECTOR STRIP], …). Cheap, and it is where you
+//      catch a bad sequence BEFORE paying for video.
+//   3. SHOT PROMPT — the video-model prompt. It cites the character card as
+//      the identity authority and the board as the staging authority, then
+//      restates the panels as PANEL BEATS so the model can't drift off order.
+//
+// Two rules carry most of the quality and are enforced by the emitters below:
+//   • REFERENCE PRIORITY — identity reference controls identity; the
+//     storyboard controls staging/motion/geography/continuity. Stating the
+//     split stops the model from copying a face off the board's rough panels.
+//   • "Do not render the storyboard sheet itself" — without it, video models
+//     happily animate the grid, borders and all.
+export const SEQUENCE_PLAN_VERSION = 1;
+// ── small helpers ───────────────────────────────────────────────────────────
+export function panelId(n) {
+    return `P${String(n).padStart(2, "0")}`;
+}
+function arrow(items) {
+    return items.filter(Boolean).join(" -> ");
+}
+function block(name, body) {
+    return `[${name}]\n${body}`;
+}
+/** "part-03" → 3. Falls back to 1 so a hand-written id never crashes an emit. */
+export function partIndex(part) {
+    const m = /(\d+)\s*$/.exec(part.id);
+    return m ? Number(m[1]) : 1;
+}
+// ── 1. character card ───────────────────────────────────────────────────────
+/**
+ * Identity sheet for one character. Deliberately close to the shared
+ * CHARACTER_CARD_PROMPT_SNIPPET used by /tools/image, but pinned to the plan's
+ * style lock so the card and the final video agree on art style — a card in a
+ * different style is the most common cause of drift at the video step.
+ */
+export function buildCharacterCardPrompt(character, plan) {
+    return [
+        `CHARACTER REFERENCE SHEET for ${character.name} (${character.code}).`,
+        `SUBJECT: ${character.appearance} Wardrobe: ${character.wardrobe} Movement quality: ${character.movement_quality}`,
+        `ART STYLE (must match the final film): ${plan.style_lock}`,
+        "LAYOUT: one single consistent character on a plain neutral light-gray studio background, laid out as a clean labeled grid — " +
+            "BODY SHOTS (full body, three-quarter, half body, head-and-shoulders neutral expression); " +
+            "a TURNAROUND row (front, side profile, back); " +
+            "an EXPRESSION SHEET of face close-ups (neutral, determined, joyful, strained); " +
+            "and a POSE SHEET of 3 dynamic action poses drawn from this character's movement quality.",
+        "CONSISTENCY: the SAME face, hairstyle, wardrobe, colors, body proportions and art style in EVERY view. " +
+            "Even flat studio lighting. Small text label under each view. No background scenery, no props beyond the character's own key prop, no logos, no watermark.",
+        "This sheet is an identity authority for downstream shots: prioritize readable face structure, silhouette and costume detail over mood or composition."
+    ].join("\n\n");
+}
+// ── 2. storyboard sheet ─────────────────────────────────────────────────────
+/**
+ * The block-grammar storyboard prompt. Every block earns its place:
+ *  • PROJECT CARD / CONTINUITY HEADER — masthead + the reference-priority split.
+ *  • SCENE PACKET — premise, geography, start→end, action chain, prop state.
+ *  • CHARACTER SANITIZATION — strips un-drawable psychology and backstory.
+ *  • IDENTITY CONSISTENCY / SPATIAL CONTINUITY LOCK — the two anti-drift rules.
+ *  • STORYBOARD PURITY — keeps labels OUT of the panel art (the video model
+ *    will animate any text it sees inside a frame).
+ *  • DIRECTOR STRIP — rhythm/escalation tracks under the grid; this is what
+ *    makes the board readable as timing rather than as nine unrelated stills.
+ */
+export function buildStoryboardPrompt(part, plan) {
+    const panels = part.panels;
+    const chars = plan.characters;
+    const purity = plan.board_style === "final"
+        ? "Panel images are finished-look frames rendered in the final film style (this board doubles as a style fit-check). " +
+            "Put panel numbers, beat names and lens tags in the header strip OUTSIDE each panel image. " +
+            "No labels, arrows, captions, subtitles, logos, watermarks, timing marks, diagrams, UI, ghost poses, duplicate bodies or technical overlays INSIDE panels."
+        : "Panel images are visual-only low-detail monochrome light-gray rough sketches: fast gesture-drawing energy, simple anatomy construction, strong silhouette readability, unfinished previz feel. " +
+            "Put panel numbers, beat names and lens tags in the header strip OUTSIDE each panel image. " +
+            "No color, labels, arrows, captions, subtitles, logos, watermarks, timing marks, diagrams, UI, ghost poses, duplicate bodies or technical overlays INSIDE panels.";
+    return [
+        `Create a ${plan.aspect_ratio} image.`,
+        block("PROJECT CARD", [
+            "Create a compact designed masthead, not a table.",
+            `TITLE: ${part.title.toUpperCase()}`,
+            `META LINE: ${part.meta_line}`,
+            `PRIORITY: ${part.priority}`,
+            `MICRO BRIEF: ${part.micro_brief}`
+        ].join("\n")),
+        block("CONTINUITY HEADER", [
+            `SEQUENCE ID: ${part.sequence_id}`,
+            "REFERENCE PRIORITY: identity reference controls identity; this storyboard controls staging, motion, geography, continuity"
+        ].join("\n")),
+        block("SCENE PACKET", [
+            `PREMISE: ${part.premise}`,
+            `LOCATION: ${part.location}`,
+            `START -> END: ${part.start_end}`,
+            `ACTION CHAIN: ${arrow(part.action_chain)}`,
+            `PROP / EFFECT STATE: ${part.prop_effect_state}`,
+            `MUST READ: ${part.must_read}`
+        ].join("\n")),
+        block("CHARACTER SANITIZATION", [
+            ...chars.map((c) => `${c.code}: ${c.appearance} ${c.wardrobe} Movement quality: ${c.movement_quality}`),
+            "Remove contradictory traits, invisible psychology, excessive costume detail, and backstory that cannot appear in a panel."
+        ].join("\n")),
+        block("IDENTITY CONSISTENCY", [
+            "Identity reference controls face, body, wardrobe, and proportions.",
+            `Keep ${chars.map((c) => c.code).join(", ")} on-model — silhouette, hair, wardrobe and key props consistent across all panels.`,
+            "Do not redesign, age-shift, or merge characters. Hold screen direction; do not flip travel direction between panels."
+        ].join("\n")),
+        block("STORYBOARD PURITY", purity),
+        block("MASTER SHOT RULE", `Panel 01 is the master: ${part.master_shot}`),
+        block("EMOTIONAL ARC", part.emotional_arc),
+        block("STYLE LOCKS", [
+            `STYLE LOCK: final video style is ${plan.style_lock}; ${plan.board_style === "final"
+                ? "render panels in that same style"
+                : "inside storyboard panels render only monochrome light-gray rough sketch"}.`,
+            `EFFECT LOCK: ${plan.effect_lock}`,
+            `ENVIRONMENT LOCK: ${plan.environment_lock}`
+        ].join("\n")),
+        block("SPATIAL CONTINUITY LOCK", part.spatial_continuity_lock),
+        block("DIRECTOR STRIP", [
+            "Bottom animatic track board aligned to panel columns. Tracks: BEAT LINE, CAMERA PATH, ACTION PATH, RHYTHM TRACK, ESCALATION MAP, STATE TRACK, STYLE TRACK.",
+            "Use shot chips, thin lines, rhythm blocks, small intensity bars, one-to-three-word labels. No seconds or timestamps.",
+            "RHYTHM TRACK format: `RHY P##: [hold|slow reveal|build|burst|impact|pause|recover|final hit] / [short block|medium block|long block] / [clean beat|match beat|smash beat|held beat|whip beat]`.",
+            "ESCALATION MAP format: `ESC P##: [L1 calm|L2 tension|L3 rise|L4 surge|L5 peak] / [flat|rise|spike|drop|release|unresolved]`.",
+            `PANEL HEADERS: ${arrow(panels.map((p) => `${panelId(p.n)} / ${p.lens} / ${p.beat}`))}`
+        ].join("\n")),
+        `CAMERA + LENS PLAN: ${arrow(panels.map((p) => `${panelId(p.n)} ${p.camera}`))}`,
+        `ACTION PATH: ${arrow(panels.map((p) => `${panelId(p.n)} ${p.action}`))}`,
+        `RHYTHM TRACK: ${arrow(panels.map((p) => `${panelId(p.n)} RHY ${panelId(p.n)}: ${p.rhythm.kind} / ${p.rhythm.block} / ${p.rhythm.beat}`))}`,
+        `ESCALATION MAP: ${arrow(panels.map((p) => `${panelId(p.n)} ESC ${panelId(p.n)}: ${p.escalation.level} / ${p.escalation.shape}`))}`,
+        `STATE TRACK: ${arrow(panels.map((p) => `${panelId(p.n)} ${p.state}`))}`,
+        `STYLE TRACK: ${arrow(panels.map((p) => `${panelId(p.n)} ${p.style}`))}`,
+        block("SEQUENCE", `Grid: ${panels.length} panels in a ${part.grid.cols}x${part.grid.rows} grid; read left-to-right, top-to-bottom as one continuous sequence.`)
+    ].join("\n\n");
+}
+/**
+ * The video-model prompt. Ordered the way the models actually weight input:
+ * authority statements first, then hard negatives, then look, then the beat
+ * list. PANEL BEATS restates the board in words so the sequence survives even
+ * when the model reads the board loosely.
+ */
+export function buildShotPrompt(part, plan, refs) {
+    const lines = [];
+    if (part.extend_from) {
+        lines.push(`extend ${refs.extendFromUrl ? `@[${refs.extendFromUrl}]` : `@[${part.extend_from} video]`} by ${part.duration_seconds}s, continuing the same shot world without restating the setup.`);
+    }
+    else {
+        lines.push(`Create a ${part.duration_seconds}-second cinematic sequence.`);
+    }
+    lines.push(`Use ${refs.boardUrl ? `@[${refs.boardUrl}]` : "@[storyboard reference]"} as the authoritative director-approved storyboard blueprint for this sequence. ` +
+        "Treat every storyboard panel as a consecutive shot within a single continuous sequence. Follow panel order exactly and do not invent alternative coverage. " +
+        "DO NOT RENDER THE STORYBOARD SHEET ITSELF — recreate the filmed sequence implied by the panels, not the physical board artwork, and never treat the board as a single image. " +
+        "Preserve camera placement, framing, lens intent, shot scale, character staging, screen direction, environmental geography, prop placement, action choreography, continuity and emotional escalation shown by the board. The storyboard is the primary source of truth for visual storytelling.");
+    for (const card of refs.characterCards) {
+        lines.push(`Use ${card.url ? `@[${card.url}]` : `@[${card.name} character card]`} as the fixed character-sheet reference for ${card.name} (${card.code}). ` +
+            "The character must strictly match the sheet: face, hair, proportions, wardrobe and art style. Do not redesign the character, change the costume, or alter the face.");
+    }
+    lines.push(`VISUAL STYLE: ${plan.style_lock}`);
+    lines.push(`ENVIRONMENT: ${part.location} ${plan.environment_lock}`);
+    lines.push(`EFFECTS: ${plan.effect_lock}`);
+    lines.push(`EMOTIONAL GUIDANCE: ${part.emotional_arc} Camera rhythm follows the board's escalation map; the piece must read as ${part.priority}.`);
+    lines.push(`AUDIO: ${plan.audio_lock}`);
+    if (plan.laban) {
+        lines.push([
+            "Use Laban movement logic throughout:",
+            `weight: ${plan.laban.weight}`,
+            `time: ${plan.laban.time}`,
+            `space: ${plan.laban.space}`,
+            `flow: ${plan.laban.flow}`
+        ].join("\n"));
+    }
+    lines.push("PANEL BEATS:\n" +
+        part.panels.map((p) => `${panelId(p.n)}: ${p.camera}. ${p.action}. ${p.state}.`).join("\n"));
+    lines.push("Do not add text, captions, storyboard labels, arrows, panel borders, grids, UI, logos, subtitles or watermarks. " +
+        "Do not cut to unrelated coverage, add characters that are not in the board, or resolve the sequence early.");
+    return lines.join("\n\n");
+}
+// ── deterministic starter plan (headless / --auto path) ─────────────────────
+const DEFAULT_RHYTHM = [
+    { kind: "hold", block: "long block", beat: "held beat" },
+    { kind: "slow reveal", block: "medium block", beat: "clean beat" },
+    { kind: "build", block: "medium block", beat: "clean beat" },
+    { kind: "burst", block: "short block", beat: "match beat" },
+    { kind: "build", block: "medium block", beat: "whip beat" },
+    { kind: "impact", block: "short block", beat: "smash beat" },
+    { kind: "recover", block: "short block", beat: "held beat" },
+    { kind: "final hit", block: "long block", beat: "whip beat" }
+];
+const DEFAULT_ESCALATION = [
+    { level: "L1 calm", shape: "flat" },
+    { level: "L2 tension", shape: "rise" },
+    { level: "L3 rise", shape: "rise" },
+    { level: "L3 rise", shape: "spike" },
+    { level: "L4 surge", shape: "rise" },
+    { level: "L5 peak", shape: "spike" },
+    { level: "L4 surge", shape: "drop" },
+    { level: "L5 peak", shape: "release" }
+];
+const DEFAULT_LENSES = [
+    "24mm wide", "85mm portrait", "macro insert", "50mm", "35mm", "24mm wide", "50mm", "24mm wide",
+    "35mm", "macro insert", "overhead", "24mm wide"
+];
+/** Panel-count → the grid the board should be laid out on. */
+export function gridForPanelCount(count) {
+    if (count <= 4)
+        return { cols: 2, rows: 2 };
+    if (count <= 6)
+        return { cols: 3, rows: 2 };
+    if (count <= 9)
+        return { cols: 3, rows: 3 };
+    if (count <= 12)
+        return { cols: 4, rows: 3 };
+    return { cols: 4, rows: Math.ceil(count / 4) };
+}
+export function slugify(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48) || "sequence";
+}
+/**
+ * A structurally-complete plan built from the brief alone. It is intentionally
+ * generic in its prose — the point is that every required field exists and every
+ * emitter produces a valid prompt, so `sequence run` works with no agent in the
+ * loop. `sequence plan` (agent-assisted) overwrites this with real direction.
+ */
+export function buildStarterPlan(opts) {
+    const brief = opts.brief.trim();
+    const title = (opts.title ?? brief.split(/[.!?\n]/)[0] ?? brief).trim().slice(0, 70) || "Untitled sequence";
+    const partCount = Math.max(1, Math.min(6, opts.parts ?? 1));
+    const panelCount = Math.max(4, Math.min(16, opts.panels ?? 8));
+    // Short, human-readable continuity stem (BREE-S01-…), not the whole title.
+    const stem = slugify(title).split("-").filter((w) => w.length > 2).slice(0, 2).join("-").toUpperCase() || "SEQ";
+    const characterName = opts.characterName ?? "Lead";
+    const characters = [{
+            slug: slugify(characterName),
+            code: "C1",
+            name: characterName,
+            appearance: opts.characterDescription
+                ?? "Single lead subject with a clear, readable silhouette; consistent face and proportions across every panel.",
+            wardrobe: "One consistent outfit throughout; no costume changes between panels.",
+            movement_quality: "Purposeful and physically grounded; weight visible in every pose."
+        }];
+    const parts = Array.from({ length: partCount }, (_unused, i) => {
+        const n = i + 1;
+        const panels = Array.from({ length: panelCount }, (_p, j) => ({
+            n: j + 1,
+            lens: DEFAULT_LENSES[j % DEFAULT_LENSES.length],
+            beat: j === 0 ? "Master" : j === panelCount - 1 ? "Final beat" : `Beat ${j + 1}`,
+            camera: j === 0
+                ? "High wide master establishing the full geography of the location"
+                : `${DEFAULT_LENSES[j % DEFAULT_LENSES.length]} coverage continuing the same action`,
+            action: j === 0
+                ? `${characters[0].code} is introduced in the situation described by the brief`
+                : j === panelCount - 1
+                    ? `${characters[0].code} lands the final beat of the sequence`
+                    : `${characters[0].code} escalates the action one clear step`,
+            rhythm: DEFAULT_RHYTHM[Math.min(j, DEFAULT_RHYTHM.length - 1)],
+            escalation: DEFAULT_ESCALATION[Math.min(j, DEFAULT_ESCALATION.length - 1)],
+            state: "Continuity holds: same location, same wardrobe, same travel direction as the previous panel",
+            style: "Consistent lighting and palette with the panel before it"
+        }));
+        return {
+            id: `part-${String(n).padStart(2, "0")}`,
+            sequence_id: `${stem}-S${String(n).padStart(2, "0")}`,
+            title: partCount === 1 ? title : `${title} — part ${n}`,
+            meta_line: "single continuous sequence / escalating action / clear start-to-finish read",
+            priority: "one readable escalation from the opening state to the final beat",
+            micro_brief: brief,
+            premise: brief,
+            location: "The single location implied by the brief, held for the whole part; no location changes mid-sequence.",
+            start_end: "Opening state established in panel 01 -> the sequence's strongest beat in the final panel.",
+            action_chain: [
+                "establish the situation",
+                "the first change lands",
+                "the action escalates",
+                "the strongest beat hits",
+                "the sequence resolves or exits on forward motion"
+            ],
+            prop_effect_state: "Key props stay physically consistent across panels; effects grow with the escalation map.",
+            must_read: "The escalation must read without any text on screen.",
+            master_shot: "full geography of the location with the lead subject clearly placed inside it.",
+            emotional_arc: "settled -> alert -> committed -> peak -> release; shown only through posture, pace and framing.",
+            spatial_continuity_lock: "All panels share one location and one screen direction. Allowed changes between panels: camera distance, camera height, subject pose and position, effect intensity. Not allowed: new locations, flipped travel direction, redesigned props.",
+            grid: gridForPanelCount(panelCount),
+            duration_seconds: Math.max(4, Math.min(30, opts.durationSeconds ?? 15)),
+            panels,
+            ...(n > 1 ? { extend_from: `part-${String(n - 1).padStart(2, "0")}` } : {})
+        };
+    });
+    return {
+        version: SEQUENCE_PLAN_VERSION,
+        title,
+        brief,
+        aspect_ratio: opts.aspectRatio ?? "16:9",
+        style_lock: opts.style
+            ?? "stylized cinematic realism, rich cinematic lighting, controlled color palette, natural motion blur, premium feature-film aesthetic",
+        effect_lock: "Effects are motivated by physical movement and stay grounded in the environment; no glow, no superhero energy, no motion-blur smears.",
+        environment_lock: "Hold one consistent environment, light direction and palette for the whole part; no texture or style drift.",
+        audio_lock: "No background music or score. Diegetic ambience, foley, impacts, texture and silence only.",
+        board_style: opts.boardStyle ?? "rough",
+        ...(opts.laban === false ? {} : {
+            laban: {
+                weight: "strong and grounded on impacts, brief lightness through jumps and lifts",
+                time: "quick through strikes, turns and drops; sustained through holds and recoveries",
+                space: "direct during committed action; indirect during turns and transitions",
+                flow: "bound in rooted stances and precise beats; free in aerial and release moments"
+            }
+        }),
+        characters,
+        parts
+    };
+}
+// ── plan validation ─────────────────────────────────────────────────────────
+/** Structural check that every emitter's required field is present. */
+export function validatePlan(plan) {
+    const errors = [];
+    const p = plan;
+    if (!p || typeof p !== "object")
+        return { ok: false, errors: ["plan is not an object"] };
+    if (p.version !== SEQUENCE_PLAN_VERSION)
+        errors.push(`version must be ${SEQUENCE_PLAN_VERSION}`);
+    for (const key of ["title", "brief", "aspect_ratio", "style_lock", "environment_lock", "audio_lock"]) {
+        if (!p[key] || typeof p[key] !== "string")
+            errors.push(`missing ${key}`);
+    }
+    if (!Array.isArray(p.characters) || p.characters.length === 0)
+        errors.push("characters must be a non-empty array");
+    else {
+        const codes = new Set();
+        for (const c of p.characters) {
+            if (!c?.code || !c?.name || !c?.slug)
+                errors.push("each character needs slug, code and name");
+            else if (codes.has(c.code))
+                errors.push(`duplicate character code ${c.code}`);
+            else
+                codes.add(c.code);
+        }
+    }
+    if (!Array.isArray(p.parts) || p.parts.length === 0)
+        errors.push("parts must be a non-empty array");
+    else {
+        const ids = new Set();
+        for (const part of p.parts) {
+            const where = part?.id ?? "<unnamed part>";
+            if (!part?.id)
+                errors.push("each part needs an id");
+            else if (ids.has(part.id))
+                errors.push(`duplicate part id ${part.id}`);
+            else
+                ids.add(part.id);
+            if (!Array.isArray(part?.panels) || part.panels.length < 2)
+                errors.push(`${where}: needs at least 2 panels`);
+            else {
+                part.panels.forEach((panel, i) => {
+                    if (panel?.n !== i + 1)
+                        errors.push(`${where}: panel ${i + 1} has n=${panel?.n}; panels must be numbered 1..N in order`);
+                    for (const key of ["lens", "beat", "camera", "action", "state", "style"]) {
+                        if (!panel?.[key])
+                            errors.push(`${where}: panel ${i + 1} missing ${key}`);
+                    }
+                    if (!panel?.rhythm?.kind || !panel?.escalation?.level)
+                        errors.push(`${where}: panel ${i + 1} missing rhythm/escalation`);
+                });
+            }
+            if (part?.extend_from && !ids.has(part.extend_from)) {
+                errors.push(`${where}: extend_from "${part.extend_from}" must name an EARLIER part`);
+            }
+            if (!part?.duration_seconds || part.duration_seconds <= 0)
+                errors.push(`${where}: duration_seconds must be > 0`);
+        }
+    }
+    return { ok: errors.length === 0, errors };
+}
+// ── agent task file (the "plan" step) ───────────────────────────────────────
+/**
+ * Task doc staged into the project folder so a desktop coding agent (Claude
+ * Code / Codex) can upgrade the starter plan into real direction. Same model as
+ * `vidfarm decompose --local`: the devcli owns the deterministic + billed
+ * steps, the agent owns the writing.
+ */
+export function buildPlanTaskMarkdown(plan, planPath) {
+    return `# Sequence plan task — ${plan.title}
+
+You are the director. Rewrite \`${planPath}\` in place so it stops being a
+skeleton and becomes real direction for this brief:
+
+> ${plan.brief}
+
+Then stop. Do not generate images or video — \`vidfarm sequence\` does that.
+
+## What you are writing
+
+\`sequence.json\` drives three generated prompts, so every field is load-bearing:
+
+| Plan field | Ends up in |
+|---|---|
+| \`characters[]\` | the CHARACTER CARD image prompt (one identity sheet each) |
+| \`parts[].*\` + \`parts[].panels[]\` | the STORYBOARD SHEET image prompt (block grammar) |
+| \`style_lock\`, \`effect_lock\`, \`environment_lock\`, \`audio_lock\`, \`laban\` | both the board and the video prompt |
+| \`parts[].panels[]\` again | the video model's PANEL BEATS list |
+
+Preview any of them without spending a credit:
+
+\`\`\`bash
+vidfarm sequence prompts --dir . --print board:part-01
+vidfarm sequence prompts --dir . --print shot:part-01
+vidfarm sequence prompts --dir . --print card:<character-slug>
+\`\`\`
+
+## Rules that carry the quality
+
+1. **Panels are motion, not mood.** Every \`action\` must describe a body or a
+   camera doing something. "She feels nervous" is not a panel; "she backpedals
+   and plants, keeping the blade between them" is.
+2. **One location per part.** Write \`spatial_continuity_lock\` as an explicit
+   list of what may change between panels (camera distance/height, pose, effect
+   intensity) and what may not (location, screen direction, prop design).
+3. **Hold screen direction.** If the subject travels left-to-right, say so in
+   \`state\` on every panel. Flipped direction is the most visible drift there is.
+4. **Escalate deliberately.** \`escalation\` should climb to exactly one L5 peak
+   per part. A board where everything is a peak animates as noise.
+5. **Start in motion** unless the brief wants a slow open. Panel 01 is the
+   master shot — full geography — but it can still be moving.
+6. **Characters are codes.** Panels refer to C1/C2, never to names. Keep
+   \`appearance\` to what a drawing can show: silhouette, hair, build, wardrobe.
+   Delete backstory and psychology.
+7. **\`audio_lock\` stays diegetic** unless the brief asks for score. Music is
+   added at the assemble step, where you control it.
+8. **Multi-part = \`extend_from\`.** Part 2 continuing part 1 must set
+   \`extend_from: "part-01"\`; the video prompt then opens with \`extend\` instead
+   of re-establishing the world. Budget ~${plan.parts[0]?.duration_seconds ?? 15}s per part.
+
+## Panel field cheatsheet
+
+- \`lens\` — coverage tag: \`24mm wide\`, \`35mm\`, \`50mm\`, \`85mm portrait\`, \`macro insert\`, \`overhead\`
+- \`camera\` — placement + move ("low side track at board level")
+- \`action\` — what physically happens
+- \`state\` — continuity: prop state, effect intensity, travel direction
+- \`style\` — one-line look note ("crest backlight", "impact spray burst")
+- \`rhythm.kind\` — hold | slow reveal | build | burst | impact | pause | recover | final hit
+- \`rhythm.block\` — short block | medium block | long block
+- \`rhythm.beat\` — clean beat | match beat | smash beat | held beat | whip beat
+- \`escalation.level\` — L1 calm | L2 tension | L3 rise | L4 surge | L5 peak
+- \`escalation.shape\` — flat | rise | spike | drop | release | unresolved
+
+## When you are done
+
+\`\`\`bash
+vidfarm sequence plan --dir . --check    # structural validation
+\`\`\`
+
+Fix anything it reports, then hand back to the user (or run
+\`vidfarm sequence run --dir .\` to execute the whole pipeline).
+`;
+}
+//# sourceMappingURL=sequence-prompts.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@officexapp/vidfarm-devcli",
-  "version": "0.21.24",
+  "version": "0.21.27",
   "description": "Local bridge for the Vidfarm Trackpad Editor. `vidfarm serve <template_id>` boots the FULL editor on localhost (disk-backed records/storage, free in-process render); edit composition.html on disk (Claude Code, Codex, etc.) and the browser live-morphs it.",
   "type": "module",
   "bin": {
@@ -24,6 +24,7 @@
     "dist/src/devcli/local-render.js",
     "dist/src/devcli/port-utils.js",
     "dist/src/devcli/process-scan.js",
+    "dist/src/devcli/sequence.js",
     "dist/src/devcli/skills.js",
     "dist/src/devcli/speech.js",
     "dist/src/devcli/stills.js",
@@ -35,6 +36,7 @@
     "dist/src/services/captions.js",
     "dist/src/services/composition-lint.js",
     "dist/src/services/provider-errors.js",
+    "dist/src/services/sequence-prompts.js",
     "dist/src/services/speech.js",
     "dist/src/services/clip-curation/**/*.js",
     "dist/src/services/clip-curation/**/*.json",
@@ -66,7 +68,7 @@
     "node": ">=22.0.0"
   },
   "scripts": {
-    "postinstall": "patch-package || true",
+    "prepare": "patch-package || true",
     "dev": "tsx --import ./src/instrument.ts watch src/index.ts",
     "dev:frontend": "node scripts/build-homepage-client.mjs --watch",
     "dev:cli": "tsx src/cli.ts",