Agent workflow

Reelsmith is designed to be driven by a coding agent. The agent does the creative work (research, the script, the animation, reviewing its own frames). The CLI does the mechanical work. A human approves every artifact that matters.

This page is written for Claude Code, which loads the skills automatically. Any agent that can read files and run commands can follow the same instructions. Commands are written reelsmith <command>: in a project made by init the agent runs npx reelsmith <command>, in a clone of the repo node bin/reelsmith.js <command>.

What the agent reads#

Config the agent needs is markdown on purpose: the agent can read it, and a human can review and edit it in a pull request.

The skills#

A typical session#

You: make me a video about why CI gets slow

1. The agent runs reelsmith new ci-slow and the research skill. It writes research.md as Status: DRAFT and shows you the TL;DR and the angle options. It waits.
2. You say "approved, use angle B". The agent flips the status to APPROVED and writes the script. It waits for you to approve the script.
3. The agent asks which voice to use. It waits. You say "Leda, performance mode".
4. reelsmith tts videos/ci-slow --voice=Leda --mode=performance, then reelsmith mix with a track that fits the mood.
5. The agent reads the style pack and writes index.html, runs reelsmith lint until it exits 0, then reelsmith sheet and scores its own contact sheet, fixing the three worst problems each round until every score is 8 or higher.
6. reelsmith sheet --stills and reelsmith draft. It sends you draft.mp4, the contact sheet and stills with its scores. It waits.
7. You give feedback. It fixes, checks the range with reelsmith clip, sends a new draft. You say "approved".
8. reelsmith approve videos/ci-slow --by="you", then reelsmith render videos/ci-slow. output.mp4 is done.
9. You say "write the publish notes and post to YouTube". It writes publish.md (waits for approval), runs --dry-run, shows the output (waits for your go), then publishes and reports the URL and the actual privacy.

The gates#

The agent never crosses these on its own judgment:

Two gates are enforced by tools as well as by the skills: reelsmith lint exits 1 on a problem (and reelsmith run stops there), and reelsmith render refuses (exit 3) without a current approval. Any change to index.html, scenes.json, the runtime, a local script the page loads (the style kit) or the images after approval invalidates it; reelsmith approve <video> --check tells whether the approval is still current.

What the agent never does#

• Pick a TTS voice.
• Set Status: APPROVED without your "approved".
• Run the final render, or reelsmith approve, without your approval of the draft.
• Publish, or publish publicly, without your explicit instruction.
• Run the YouTube sign-in: it needs you to click Allow.
• Ask you for audio levels that config/audio.md already defines.
• Print or commit tokens and secrets.

Tips#

• Effort: use high effort (or max) when the agent writes a new index.html or a new script, medium for small fixes and re-renders.
• Iterating on a script: after you edit a line, reelsmith run videos/<name> --voice=<v> redoes tts, mix, lint, sheet (with stills) and draft in one go; --until=<step> stops earlier. In sentence mode only the changed line is re-synthesized. The mix step uses music.defaultTrack, else the track the video was mixed with last time, else it is skipped; the tts step is skipped for a recorded take.
• Checking one scene: ask for a range render; reelsmith clip videos/<name> --from=S --to=S takes seconds.
• On your phone: reelsmith preview videos/<name> --lan and scan the /qr page.
• Something broke: ask the agent to run reelsmith doctor first.