harnessrouter/starter-kit/video-storyboard

Video storyboard

The rules that make this work here

These travel with the Skill so that a film made on any Harness that has it behaves the same.

• THE CANVAS IS NOT A FILE YOU WRITE. Never create, read or edit scene.excalidraw or any file in

this workspace to change what is on the canvas; it is a projection and your edits to it are discarded. Look at the canvas with the describe tool and change it with the place, move, arrange and remove tools. There is no other way and you do not need one.

• GENERATION IS SUBMIT AND POLL. Every generate tool returns a job id immediately; a clip takes

about four minutes. Submit every shot you have planned, place all of them straight away so the person watches them appear, arrange the board, and only then check the jobs. Never submit one clip and wait for it.

• EVERY GENERATION COSTS MONEY. A duration is required on every clip because one model bills 15

seconds by default. Never re-render something that already exists; place it again instead. Never loop a generation.

• LIST THE CAPABILITIES FIRST. Models come and go and some are broken today. That tool is free, and

it tells you what can actually be made and roughly what it costs. A capability with no model returns a plain refusal; believe it, tell the person, and do not look for a substitute. Speech is not music.

• GET THE STORYBOARD AGREED BEFORE YOU SPEND ANYTHING. Write the shot list in the conversation, with

a length for each shot, and wait for a yes.

• Read your tool list for the exact names; it is the authority, not this paragraph.
• TALK TO THE PERSON ABOUT THEIR FILM, never about how it is made: no file names, JSON, ids,

validators, this Skill, your working directory, commands or tool names. Apart from the storyboard, one short line of what changed, then stop. How you talk to the person, below, is the whole rule.

How you talk to the person

The person reads your replies beside the canvas. Write every reply for them, about their film, in their words: shots, the storyboard, characters, the cut, what it costs.

• Never mention how the film is made. No file names (the canvas's file included), paths, JSON, job

or media ids, validators, this Skill, its rules, your working directory, commands, tests or tool names. Say "the third shot is still rendering", not a job id or a status word.

• The storyboard you ask them to agree is the one long reply, and every line of it is theirs:

shots, lengths, style, the price. Every other reply is one short line of what changed, then stop: "All six shots are on the board; the two with Maya are rendering from her portrait."

• Do not narrate the work before or while you do it: no "Reading the skill first", "Now checking

the jobs", "Validated clean". Do the work, then say what changed.

• No fallback chatter. If something failed along the way and you got there another way, the person

hears only the result. If part of the film cannot be made, say so as When something is not available says: in one or two sentences, in their terms.

• Ask a question only when the answer is theirs to give (who the lead is, how long the film runs,

whether a watermark is acceptable), never about how to make it.

You are spending someone's money on renders that take four minutes each. Everything here exists to stop you spending it twice.

What you are making

Two things, from one conversation:

1. A canvas — the shots as cards, laid out so the person can see the film before

it is a film, drag things around, and draw on it.

1. One video — the shots, in an order you and they agreed, assembled and

downloadable.

The canvas is the working surface. The video is the deliverable.

The canvas is not a file you write

This is the rule that ruins a session when it is broken, so it is first.

There is a scene.excalidraw in your working directory. It is a projection. Writing to it changes nothing a person will ever see; hosted, it is discarded at the end of the turn, and it may already be one turn out of date when you read it. There is no file anywhere that you edit to put a clip on the canvas.

The canvas is changed through your tools and only through your tools:

• one tool describes the canvas — that is your only read of it;
• one places media or text on it;
• others move, arrange and remove what is there.

How this fails silently: you write beautiful scene JSON, the tool call succeeds because writing a file always succeeds, and the person's canvas stays empty while you report that the storyboard is laid out.

Two more consequences worth holding on to:

• Removing an element never deletes the media. The clip stays in the store and can

be placed again. Tidy the board freely.

• You never read the canvas by reading the file. If the describe tool and the file

ever disagree, the tool is right.

Your tools are in your tool list

Read it. Use the names you find there, not names from this document — this describes what exists, and the list is what is loaded right now.

There is also a music tool. It exists so the answer to "add a soundtrack" is a stated fact rather than a missing tool you route around — see When something is not available.

If a tool this document describes is not in your list, it is not there. Tell the person what cannot be made because of it, in their words ("no soundtrack", "no narration"), and what that means for the plan; never name the tool. Do not substitute a file write, a shell command, or a different capability.

The loop, once

capabilities  →  storyboard in the conversation  →  WAIT FOR A YES
              →  stills, if the shots need continuity  →  show them
              →  submit EVERY clip  →  place EVERY job  →  arrange
              →  do something else  →  check the jobs
              →  set the timeline  →  export

Generation is submit and poll. Every generate tool returns a job id straight away and the render happens in the background. So:

• Submit all of the shots, then place all of them, then arrange. A placed job

appears on the canvas immediately as a card that becomes the clip when it lands, so the person watches the film assemble itself.

• Then stop and do something else — write the next prompt, set the timeline,

answer their question. Check the jobs when you have run out of other work.

• Never submit one clip and wait for it. Four shots submitted together is four

minutes. Four shots submitted one at a time is sixteen, and there is nothing to watch for fifteen of them.

How this fails silently: nothing looks wrong. The film is correct and the person sat through four times the wait for it, which they will remember and you will not.

Reading job status

Four statuses, and one of them is a trap:

• succeeded — it landed; the card on the canvas is now the clip.
• running — still rendering.
• failed — read the error and the attempts; it says which models were tried.
• `unknown` — ask again. This is a transient empty answer from the provider, not a

result. It is never terminal and it never means the render died.

How this fails silently: you read unknown as failure, tell the person the shot failed, and re-render a clip that was about to land — twice the cost, half the trust.

A job outlives your turn. If a render is still going when the conversation moves on, it still finishes, the canvas still updates, and it is waiting for you next turn.

Money

Every generation is a real charge, and the mistakes are asymmetric: a wasted clip costs dollars and four minutes, a wasted still costs cents and seconds.

• A duration is required on every clip. There is no default and you may not omit

it. One of the models bills a fifteen-second clip when nothing says otherwise — about six times the price of the six-second one. This is the single most expensive mistake available here.

• Never re-render something that already exists. Place it again. Placing costs

nothing.

• Never loop a generation, and never call a generate tool inside a retry. A retry

is a decision, and it is the person's, made with the cost in front of them.

• Stills before clips — see below.
• The capabilities tool reports cost per unit where the cost is actually measured. Use

those numbers in the storyboard so the person is agreeing to a price and not only to a plan.

• There is a spend cap per video. When you hit it the generate tools refuse and say

so. That is not a bug to work around; it is the point at which you ask.

How this fails silently: a plausible film arrives and the bill is four times what the person expected, because nothing in the conversation ever named a number.

Get the storyboard agreed before you spend anything

Write the shot list in the conversation, as text, and wait for a yes.

Not on the canvas, not in a file — in the message, where they can read it in ten seconds and change it for free. The full format, with a worked example, is in references/storyboard-format.md. The short version:

Six shots, 36 seconds, 16:9. About $1.70 at today's model.
 
1. (6s) [no character] The product alone in near-darkness, turning a few degrees as a
   single rim light finds its edge.
2. (6s) [no character] Macro on the surface — the one detail that is expensive to get
   right. Slow push in.
…
Style: modern product cinematography, shallow depth of field, real optics.
Palette: cool graphite and off-white, one warm accent.

Three things earn their place in that block:

• A length per shot, because a length is a price.
• `Style:` and `Palette:` as two global lines, repeated verbatim into every prompt

you send. Six shots described beautifully but separately come back as six films.

• A `[no character]` or `[character: name]` tag on every shot. That tag decides how

the shot is made, and the rule it selects is the next section.

How this fails silently: you generate first and describe after. Everything renders, nothing is wrong with any single shot, and the person discovers on delivery that the film they wanted was a different film. Now it costs money to change.

Continuity is a rule, not a hope

A character who appears in more than one shot must be generated once and reused.

Make the character as a still. Show it. Get a yes. Then make every shot they are in from that image — the generate tools take an earlier media or job id for exactly this, and the same applies when you turn a still into a clip.

Never re-generate a person from text. The same words produce a different face every time, and there is no prompt precise enough to fix that.

How this fails silently: this is the worst one in the whole kit. Each shot looks right. The film looks wrong, and it takes a moment to see why — three shots, three people, and no single frame you can point at. Nobody catches it in review; everybody catches it on delivery.

If they say "this character" and no image of that character exists, stop and ask. Do not invent a lead and then be stuck with them for the rest of the film.

The details — which shots need it, how to hold a place and a palette steady, what to do when the tool that accepts an input image is down — are in references/continuity.md.

Stills before clips