The crew: specialist sub-agents for the director

Read this when a job is in studio mode, is publish-bound, or is long enough that parallel scene building pays off, and you are about to hand work to a sub-agent. Crew members follow references/crew/rules.md and their own brief in references/crew/.

You are the director. The crew does focused jobs from files and hands back files and a short status. You stay the only one who talks to the user, writes the ledger (showtime job note), the studio folder (board.json, brief.md, decisions.md), the main project's index.html and showtime.json, and who renders, runs qa and delivers.

1. When to use it#

Never dispatch for something one or two commands do (brand init, one voice line, the template mix). Follow-ups go to the same member (resume it, section 3), not a new one. If the user says "no crew", note it under Preferences in brief.md (or as a job note) and do everything inline. The studio offer line may say that studio uses the crew and takes longer.

2. The roster#

"Session" means the agent inherits your model; the Agent tool's model parameter overrides any row (use the session model for a voice director translating a script).

3. How to dispatch#

1. Make a task folder: <job>/crew/<task-id>/ (for example crew/motion-s3/, crew/pitch-cd/).
2. Write TASK.md there from this skeleton:

# <role>: <one-line task>
Job: <absolute job folder>     Mode: quick|studio     Publish-bound: yes|no     Platform: <platform>
Skill: <absolute skill folder>
Read: references/crew/<role>.md, then only: <references and sections>
Inputs (read-only): <contract or brief.md, SHOWTIME.md, brand.json, storyboard rows, cue table,
                     voice/timeline.json, capture folder, transcripts ...>
You own (write only here): <job>/crew/<task-id>/  [+ exclusive project paths, if any]
Deliver: <files>
Done when: <a checkable line>
Heavy commands allowed: <e.g. showtime check; showtime snap --at, 6 frames at most> (nothing else)
Assumptions already made: <...>     Out of scope: <...>

3. Dispatch with two lines of prompt, no chat history: "Read <skill>/references/crew/rules.md and <skill>/references/crew/<role>.md. Your task: <job>/crew/<task-id>/TASK.md."
   • Claude Code with the plugin: Agent tool, subagent_type showtime:<role>.
   • No such agent type (a linked dev install, another host): a general-purpose sub-agent with the same two lines. Name a vision-capable model for roles that read images.
   • No sub-agents at all: do the task yourself from the same brief, and say so (a critic becomes a labelled self-review, references/review.md section 3).
4. Independent members go out in one message (several Agent calls together). Tell the user in one line who is working and for how long ("Creative director, brand designer and scriptwriter are on it, about 3 minutes"). Wait for their notifications; never poll in a sleep loop.
5. Follow-ups (a fix note, new timings) go to the same member with SendMessage, which keeps its context; write longer notes into its task folder and send the path.

Validate before fan-out. Before parallel builders start: freeze the cue table, write the theme or brand CSS, fetch everything in the storyboard's assets-needed.txt, and run showtime check on the skeleton project. A bad path should fail once, in seconds, not in four agents.

4. Patterns#

A. Studio pitch round. You: job init, studio init, one capture per page you need (one at a time), brief.md, and a draft kit, showtime brand init ... -o <job>/brand.json (light, a second), so the style frames start from real tokens. Then in parallel: creative director (concepts and style frames from the draft kit), scriptwriter (facts, claims, hooks) and, only when the draft needs judgement (brand init warned, guessed the accent from a tint, found no logo, or there is no source kit), the brand designer correcting it (kit only; looks come after the pick). Merge:

1. Paste the creative director's concepts.json cards into board.json (they use the board's concept fields) and add the kit's palette.
2. The scriptwriter's hooks: swap one into a card's hook when it is stronger and sourced, or offer two or three as an opening-line question with a recommendation. claims.json stays for the researcher.
3. A corrected kit from the brand designer replaces <job>/brand.json; if its accent changed, the style frames are stale: fix the comps' tokens and render again with --replace.
4. Frames, one command at a time: showtime studio frame <job> --concept C1 --html <job>/crew/<task>/comps/c1.html --at <t> (a page outside studio/ is served from its own folder).
5. studio board, studio open, end the turn.

B. After the concept pick. In parallel: scriptwriter (script), sound designer (three beds), voice director (three voices reading the picked hook), brand designer (three looks, when the look phase is on). Then the storyboard artist (needs the script) and the researcher on claims.json, in parallel. Before lock: creative director sign-off on the storyboard and animatic; its points become storyboard notes you apply or show the user.

C. Build (after lock). Validate before fan-out, then in parallel: one motion designer per scene or group, the sound designer on project/audio/, the voice director on project/voice/ if the VO is not final. When the voice lands and changes durations, retime the scenes from it (showtime retime <project> --from-voice <project>/voice/timeline.json), then send the new times to the motion designers and the sound designer.

D. Critic. Publish-bound studio: round 1 on the first look (a --preview render), where fixes are cheap; round 2 on the final candidate. Quick publish-bound: one round, on the final. Dispatch the critic with only the CRITIC.md path (references/review.md).

E. Fix loop. A finding or user note about one scene goes back to that scene's motion designer; audio notes to the sound designer; claim notes to the scriptwriter and researcher. Re-merge only what changed and re-render the affected range (--from/--to).

F. Footage. The editor alone (it owns edit/), then the sound designer for music under the cut, the researcher for on-screen claims and lower thirds, the critic when publish-bound. You confirm every dropped take or sentence in cuts.md with the user before the final.

G. Localization. One voice director per language, two at a time at most (TTS is CPU-heavy); then you retime and render each language, one after another.

5. Merging results#

1. Read RESULT.md, check the listed files exist, and verify with your own command before building on anything (showtime check, showtime snap <project> --at ..., showtime audio meter). "The agent said done" is not evidence.
2. DONE_WITH_NOTES: read the notes, decide, log it (showtime job note --assumed "decided X because Y").
3. NEEDS_INPUT: answer from the source when you can; otherwise take its recommended default (quick) or add it to the next studio question round (5 questions at most). Resume the member with the answer.
4. BLOCKED: fix the cause (a missing asset, a wrong path) and resume, or do the task inline. Never ship a degraded result silently.
5. Conflicts (copy longer than its slot, a bed fighting the voice): the locked storyboard and the durations win; log the ruling and mention it in the delivery card.

Scene fragments. Merge in storyboard order into the main project: put each fragment's section.html inside the page's stage element after the previous scene (replacing the template's placeholder scene), set its data-start to #<previous scene id> (the first scene keeps 0; the templates already chain scenes this way, references/stage-api.md has the time grammar), keep its data-transition, link its s-<sid>.css and s-<sid>.js, and copy its assets/ into the project. Then showtime check <project> and showtime snap <project> --every 1, and read the sheet with an eye on the seams between scenes.

6. CPU budget#

Writing and design roles cost tokens, not CPU: run them all in parallel. Commands that launch a browser, speech recognition, TTS or long encodes share the machine:

Slots: a third of the CPU cores, between 1 and 3 (6 cores give 2). Parallel motion designers: at most slots + 1 (they spend most of their time writing), and each TASK.md allows single snap --at frames, never --every sheets. Never run speech recognition while a browser capture runs. Your final render (--workers 3 at most) starts only after every builder has returned.

7. Cost#

Every dispatch starts a fresh context: the brief (2-4k tokens), the references it reads (5-20k) and its work. Rough totals: writing roles 20-60k tokens, scene builders 60-200k (they look at images), critic 40-100k. The crew saves your own context (you never read transcripts or scene code), but a studio job with a full crew costs several times a quick one. Keep quick mode inline.

Measured on a 20 s teaser pitch round (fictional notes app, two page captures, 3 concepts + wildcard, 4 style frames): about 8 minutes done inline one role after another, about 4 with the three members in parallel, and roughly 100k tokens of your own context when done inline (reading the references and looking at captures and frames is most of it). CPU was light: the two captures (about 50 s) and the frames (4 in about 15 s) were the only heavy steps. Doing a round inline, keep to the brief: one frame per concept, contact sheets rather than single shots.

View or edit this page on GitHub