Write the brief
Start a film with bin/vawe new. It asks for the missing details and writes films/<name>/brief.md.
At the end of this page you have films/<name>/page.html (a valid starter) and films/<name>/brief.md, the briefThe brief is films/<name>/brief.md, the file of facts and plans for one film. that every later stageA stage is one step of the loop, with one command and one result. reads. This is stage 1 of the loopThe loop is the ten stages that make a film: brief, references, design kit, states, board, draft, motion pass, critique, fix and final..
You need a vawe checkout and an ask in your own words, such as “a 5 s sting for a coffee brand”.
Steps
Print the open details
bin/vawe new hello --request "a 5 s sting for a coffee brand" --questions-jsonThis writes nothing. It prints the details that the ask leaves open, as calls of at most 4 questions each, with the required details first. The list lives in DETAILS in harness/lib/measured-brief.mjs.
Without --questions-json, the verb prints the same questions as text and stops.
Answer them in a file
Write one key: value line for each detail. The keys are subject, message, show, format, assets and ending.
subject: Hollow, a coffee roaster for people who work from home
message: the first cup is the best part of the day
show: a cup filling, and the word "Hollow"
format: 6 s, 16:9
assets: invent everything
ending: the Hollow wordmarkFor one answer only, pass --detail key=value (repeat the flag for more).
Write the brief
bin/vawe new hello --request "a 5 s sting for a coffee brand" --answers answers.txtThe verb picks a templateA template is a file in prompts/ for one type of film, with when to use it, the brief to fill in, a question bank and known mistakes. from your ask and writes the two files.
Take the defaults when nobody can answer
bin/vawe new hello --request "a 5 s sting for a coffee brand" --defaults--defaults guesses every open detail and marks each guess (guess: change me) in the brief. Use it when no person is there to answer, such as in CI.
Choose a template
Add --from to pick the template yourself. The default is the row of guides/ROUTING.md that your ask, the name and --length point at.
bin/vawe new hello --from prompts/story-explainer.md --answers answers.txtThe prompts/ folder holds 11 templates:
| Template | Use when |
|---|---|
showreel-one-liner | no brief, a taste probe |
brand-launch-from-url | a real product from a URL, with its own kit and real captures |
ui-morph-loop | one element becomes 8 to 12 UI states and loops |
reference-rebuild | a reference mp4 must be matched |
directors-brief-long-form | over 60 s, or more than one session or agent |
story-explainer | explain a topic with invented visuals |
music-video-beat-synced | a song exists, and every cut lands on its beat |
beat-sheet | any film over one beat: the shot table before code |
interactive-lab-capture | a mechanism as a working model, then a scripted tour of it |
production-brief-acceptance | a claim that someone other than the author must sign off |
pixel-art-sprite | a 16-bit sprite loop on a logical canvas |
guides/ROUTING.md maps a request to nine film types, and a type to one of the first nine templates (a sting takes beat-sheet). Two rules decide most cases:
- A real product from a URL is a brand launch (
prompts/brand-launch-from-url.md). - A reference mp4 that you must match is a reference rebuild. Use
--refand read Match a reference film.
If two types fit, the shorter film wins. --length, --aspect and --title write their values into the brief and the page. --aspect takes any whole ratio, such as 16:9 or 9:16.
What you see
The verb prints the question bank of the template with a default for each question. It writes films/hello/brief.md with each default filled in and marked [unanswered: default taken]. A field that the ask did not answer holds a guess marked (guess: change me).
The brief also has an “Ideas” section for the later stages. The verb ends with a next: line that names the next stage.
The sections of the brief
The brief is measured. A number that a program can measure is a number. A value that it cannot measure yet is a guess, marked (guess: change me). The agent replaces each guess with a measured value or its own choice. The sections come in this order (SKELETON in harness/cli/new.mjs):
- Inputs. The questions of the template, each with its default marked
[unanswered: default taken]. - Task. What the film is, who sees it, the message and the spectacle second.
- Taken from. Four to six reference frames, with what each one gives.
- Directions. Three directions from three families (type, object, graphic). The agent picks one and says why.
- Signature. Six dials: band, ease, stagger, seam, palette and thread. The page repeats them in
<meta name="signature">. - Look. Numbers, not adjectives: colours, the typeface, type as a fraction of frame height.
- Design system and kit. Palette roles, type, and the ground layers.
- States. One static key frame per world, built from the kit before any motion.
- Ideas. A table with four ideas for each beat and cut, and the pick with its reason.
- Board. A plan for time: rhythm, a named move per cut, and the sound.
- Motion pass. One row per cut, after the draft.
- Keep and swap. For a reference film only: KEEP or SWAP for each line of its
SPEC.md. - Spec. Three tables, in seconds and percent of frame: shots, words and objects.
- Acceptance. Targets for the checks, with the measured value next to each one.
- Gates, Pitfalls and Deliver. The order of the stills, the draft loop and the final, the pitfalls, and the files to hand over.
- First draft. The taste list to read and the
bin/vawe devcommand.
The slowest move runs at least 3 times the fastest (taste/rules/speed-bands.md). For the page contract, see The page.
What good looks like
- Every
(guess: change me)is a number or a name, not a hope. A value that you keep on purpose loses its marker. - The brief names a genre or a reference. A brief with no anchor reads like a template.
- Facts only. The brief holds no plan for time yet: the board comes later.
Common mistakes
| What you see | Why | What to do |
|---|---|---|
The brief is full of (guess: change me) | You used --defaults | Replace each guess with a measured value, or keep it and delete the marker |
| The film type is wrong | The ask matched another row of guides/ROUTING.md | Run the verb again with --from prompts/<template>.md |
| The verb prints questions and writes nothing | You gave no --answers, --detail or --defaults | Answer the questions, or add --defaults |
Inputs that raise quality
- A real product URL, crawled, not invented. See Brand reflection.
- A reference film.
bin/vawe see <ref.mp4> --specmeasures it intoSPEC.md. Mark each line KEEP or CHANGE, then rebuild. - Real data. Numbers and copy are true and looked up, never made up for effect.
- The film type, if you know it. It saves a routing step.
- A genre anchor and a ban list. A default you do not exclude is free for the agent to use.
What to avoid
- Do not ask for fake product UI. A screen, logo or photo in the plan must trace to a real capture (
prompts/brand-launch-from-url.md). - Do not name hex codes or easings to fix a weak film. Fix the anchor and the ban list.
What to say when it is wrong
Name the symptom, not the cause. “Beat three reads as a slide, nothing moves but the text” is better than “make it more dynamic”. The agent can find the cause. It cannot guess what you saw.
To change direction instead of fixing a detail, change the anchor and the ban list.