Use with an agent
Set up Claude Code, Codex or Cursor to make vawe films, and see what the agent does at each stage of the loop.
By the end of this page, an agent in a vawe checkout reads the house rules, loads the skillsA skill is a SKILL.md file of instructions that an agent loads for one task, such as vawe-page for writing a page. and follows the loopThe loop is the ten stages that make a film: brief, references, design kit, states, board, draft, motion pass, critique, fix and final.. Every command it runs is logged under its name. Install vawe first: Install.
What the agent reads
vawe keeps its rules in one file, AGENTS.md at the root of the checkout. Codex, Cursor and other agents read AGENTS.md. Claude Code reads CLAUDE.md, which points to AGENTS.md.
AGENTS.md holds the setup, the hard rules, the ten stages of the loop, the shell rules and an index of the docs. The skills add the detail for one task each.
The skills
A skill is a folder in skills/ with a SKILL.md file. Any agent can read a SKILL.md. The skills run inside a vawe checkout.
| Skill | Load it when |
|---|---|
html-to-video | You start here: a film is asked for and none exists yet. |
vawe-brief | A request has no brief.md yet. |
vawe-page | You write or edit page.html. |
vawe-transitions | You plan the cuts between worlds. |
vawe-critique | A draft is rendered and needs a look, before any fix. A session that did not write the page does this. |
vawe-reference | A reference mp4 must be matched. |
AGENTS.md tells the agent to read skills/<name>/SKILL.md before its stage, so a checkout needs no install.
Install the skills
The skills are also published in vawe-hq/skills, so an install does not download the whole repository. Use one of these:
npx skills add vawe-hq/skills
claude plugin marketplace add vawe-hq/skills
claude plugin install vawe@vawe-skillsThe first line works for any agent that the skills CLI supports. The other two are for Claude Code.
Claude Code
Open Claude Code in the vawe checkout. It reads CLAUDE.md, which loads AGENTS.md. The repository does not track a .claude/settings.json, so each person registers the hooks in harness/live/.
The hook harness/live/stage-say.mjs runs on each prompt. It names the next command for the film you edited last. It stays silent when no page changed in the last three hours.
Codex, Cursor and other agents
Tell the agent to read AGENTS.md first. Any agent that reads files and runs shell commands can follow the loop. Without a hook, each verbA verb is one command of the vawe CLI, such as new, dev or ship, run as bin/vawe <verb>. of bin/vawe prints a next: line that names the next stageA stage is one step of the loop, with one command and one result..
What the agent does at each stage
| Stage | The agent | The command |
|---|---|---|
| Brief | Asks for the missing facts, then writes the briefThe brief is films/<name>/brief.md, the file of facts and plans for one film.. With --defaults it guesses and marks each guess. | bin/vawe new <name> --request "<the ask>" |
| Reference study | Lists the references and fills “Taken from” in brief.md. | bin/vawe refs list |
| Design system and kit | Writes DESIGN.md and kit/ for the film. | none |
| States | Builds one key frame for each world. | bin/vawe frames <page> |
| Ideas, board | Fills “Ideas” and “Board” in brief.md, then makes the storyboard. | bin/vawe storyboard <page> |
| Draft | Renders a half-size draft with sound. --silent leaves the sound out. | bin/vawe dev <page> |
| Motion pass | Reads a strip of every cut and writes one “Motion pass” row for each cut. | bin/vawe strip <page> --cuts |
| Critique | Runs in a fresh sessionA fresh session is an agent session that did not write the page, in a separate terminal or agent. that did not write the page. | bin/vawe critique <page> |
| Fix | Renders again only the seconds that the critique names. | bin/vawe dev <page> --from s --to s |
| Final | Asks for a fresh judge. The owner approves. Then the agent ships and waits. | bin/vawe judge <page> --fresh, bin/vawe approve <page>, bin/vawe ship <page>, bin/vawe wait <page> |
The critique and the judge run in a session that did not write the page. An agent never judges its own page or records its PASS.
Rules for the shell
AGENTS.md lists the mistakes that agents make in the shell:
- The shell is zsh. Quote every glob and every
?. - Never use
sleep. Wait withbin/vawe wait <page>. - Never pipe
bin/vaweintotail,headorgrep. The pipe hides the exit code. - Read the last line of each verb:
vawe: <verb> ok|FAILED (<reason>) in <s>s.
Use a bin/vawe verb before raw ffmpeg or Chrome. If no verb does the job, say so in your report.
The run log
Each verb adds one JSON line to out/<film>.runs.jsonl. The line holds the time, the verb, the film, the session, the agent name, the model and the git state.
To name an agent, set two variables in the shell before the first command:
export VAWE_AGENT=writer-1
export VAWE_MODEL=<model>VAWE_AGENT is the only way to name an agent. A subagent shares the session id of its parent, so the session cannot tell them apart. Without VAWE_AGENT, the log writes the first 8 characters of the session id, a # and a short tag. A name with a # counts as unnamed.
The critique must come from another session than the author. Another VAWE_AGENT name in the same session does not count: ship refuses it. bin/vawe runs <name> shows a critique line with the agent that ran it.
Read the log with vawe runs:
bin/vawe runs hello # time, failures and the draft series of one film
bin/vawe runs --all # one row for each film of the last 30 days, then medians for each model