stick-stage
AGENTS.md2 starsChanged 15 days agoMITView on GitHub
This file is the instructions for coding agents (Codex, Cursor, Copilot, Claude Code and others). CLAUDE.md imports it, so edit this file only. Comedy-skit and science-short engine on Remotion. Open source (MIT); Tamtree uses it for its own channels. Characters draw as stick figures or as toons (style.build). The ../planning/ paths below are maintainers' private planning notes, not in this repo. Plan: ../planning/2026-09-26-revised-plan/plan.md (milestones, gates, data contracts). Science channel: ../planning/2026-09-29-science-channel/. Toon tier: ../planning/2026-10-02-toon-characters/. Decisions not in a plan go in…
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository13 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- llms.txtllms.txt
- crew-episodeSkill
- explainerSkill
- science-shortSkill
- shorts-editorSkill
- skit-directorSkill
- story-episodeSkill
- the-catch-stagingSkill
- the-catch-storySkill
- toon-characterSkill
- topic-to-videoSkill
- whos-wrongSkill
The file
We split this AGENTS.md into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Frame-pure rendering: Every visual is a pure function of (frame, props).
- Distinctive: line 12
Small, typed modules: No file over ~300 lines.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
StickStage — agent guide
This file is the instructions for coding agents (Codex, Cursor, Copilot, Claude Code and others). CLAUDE.md imports it, so edit this file only.
Comedy-skit and science-short engine on Remotion. Open source (MIT); Tamtree uses it for its own channels. Characters draw as stick figures or as toons (style.build). The ../planning/ paths below are maintainers' private planning notes, not in this repo. Plan: ../planning/2026-09-26-revised-plan/plan.md (milestones, gates, data contracts). Science channel: ../planning/2026-09-29-science-channel/. Toon tier: ../planning/2026-10-02-toon-characters/. Decisions not in a plan go in DECISIONS.md.
Core rules
- Frame-pure rendering. Every visual is a pure function of
(frame, props). NouseState/useEffectfor animation, no CSS animations, noDate, noMath.random(). Use seededrand()/noise()fromsrc/engine/lib/seed.ts. - Everything is data. Characters, poses, expressions, sets, props and skits are JSON validated with zod, and every document carries
schemaVersion. Components never hardcode timing. - No network at render time. TTS and lip-sync run in a prepare step and are cached by content hash. The render reads only local files.
- Keep the engine app-agnostic.
src/engine/**never callsregisterRoot, never readsprocess.env, and never touches the filesystem. Onlysrc/app/**andscripts/**may. (Enforced by eslint andtests/engine-rules.test.ts.) - Small, typed modules. No file over ~300 lines.
- Original characters only. Match the genre, not someone's cast.
Commands
pnpm bootstrap/pnpm diagnose/pnpm demo: first run (Rhubarb + Chrome into place; what's missing; renderfinewithout TTS). Notpnpm setup/pnpm doctor: those are pnpm built-inspnpm try "<topic>": premise (yours, orLOCAL_LLM_*'s) → Kokoro voices →out/<id>.mp4pnpm dev: Remotion Studiopnpm test/pnpm typecheck/pnpm lint: run all three before every commitpnpm still <Comp> out/x.png --frame=N: single still (layout checks only)pnpm sheet <Comp> <from> <to> <step> [--cols=6] [--scale=0.25]: contact sheet PNG inout/pnpm story prompt|draft|assets|prop|promote: story episodes (shape cast): writer prompt, reply → skit, missing-asset report, draw a prop, promote a prop (docs/stories.md)pnpm render <skitId> [out.mp4] [--debug] [--frames=a-b]: prep → compile →out/<skitId>.mp4forpublic/skits/<id>/skit.jsonpnpm render <Comp> out/x.mp4 [--frames=a-b]: any other composition (labs) passes through toremotion render. Motion is reviewed as video, not stills.pnpm compile <skitId>: validate a skit, print diagnostics or the director's choices (beats, cuts and why, punch-ins, SFX), writegenerated/timeline.jsonpnpm sfx: regenerate the synthesized SFX library (public/sfx/,src/data/sfx.json);pnpm render SfxLab out/SfxLab.mp4plays them allpnpm still SetLab out/SetLab.png [--props='{"kits":["park"],"tileWidth":200}']: every set part × 3 palettes × 3 seedspnpm voice:say <skitId>: dev stand-in for the tamtree harness TTS; macOSsay→public/skits/<id>/voice/+voice.jsonpnpm voice:tts <skitId>: the same with Kokoro in-process (orLOCAL_TTS_BASE_URL); voice map inscripts/lib/kokoro-voices.tspnpm approve <skitId> --by=<owner> [--check]: science skits: list claims, then pin the owner's sign-off to the content hash;pnpm render <skit> --postand final service renders refuse an unapproved or changed skitpnpm viz:labthenpnpm render VizLab out/VizLab.mp4: every figure kind with its cues (typesets the lab's equations first);--props='{"wide":true}'shows the explainer kinds at 16:9pnpm map:data <ne_110m_admin_0_countries.geojson>: re-bake themapfigure's world (src/data/maps/world-110m.json)pnpm prep <skitId> [--require-rhubarb]: voice.json → Rhubarb mouths + script-aligned word timings →generated/voice.prepared.json(hash-cached, no network). Rhubarb:RHUBARB_PATH,tools/Rhubarb-Lip-Sync-*/rhubarb(gitignored), or PATH
Skills
topic-to-video(skills/topic-to-video/SKILL.md): a topic → a ~30 s skit, end to end (writes the jokes, stages, renders, packages). Use it when asked to "make a video about X".skit-director(skills/skit-director/SKILL.md): stages a human-written premise; never writes or changes a line.science-short(skills/science-short/SKILL.md): a myth-flip science short with Vera and Gus, figures on the word, claims with sources; never approves.toon-character(skills/toon-character/SKILL.md): add or change a toon character, a garment/hair kind, or a toon-only pose fix without touching stick drawings.story-episode(skills/story-episode/SKILL.md): an idea → a narrated 16:9 shape-cast story (places, new characters as specs, drawn props), checked and rendered.explainer(skills/explainer/SKILL.md): a topic and its data → a narrated 16:9 data story (format: "explainer"): charts, maps and counters bound to datasets, spoken numbers checked, chapters, variety rules.the-catch-story(skills/the-catch-story/SKILL.md): a "The Catch" case script: a human, relatable, useful money story (topic test, five acts, fast-voice lines, sourced numbers).the-catch-staging(skills/the-catch-staging/SKILL.md): a The Catch script → storyboard and explainer skit in the night-shift world with Nickel, data as objects, SFX and music cues.whos-wrong(skills/whos-wrong/SKILL.md): a "Who's Wrong?" episode: a petty two-sided argument with Bram and Tess, the verdict meter, theargumentstyle's fast pace; the team writes the twist.crew-episode(skills/crew-episode/SKILL.md): an episode of the relatable three-person channel (Mitch, Ollie, Maya on the train): 2-second hook, laugh, Maya's closing thought as the train stops, packaging and multi-part rules; the team approves the jokes.
Path-scoped rules live in .claude/rules/ (toon-rig.md for the rig, characters and poses; shape-rig.md for the shape tier, story kit and places; science-skits.md for skits, figures and approval).
Voice
The engine and the render service never call a TTS or an LLM. In production the tamtree agent harness generates audio (+ optional word timings) and writes voice.json; see docs/voice-contract.md. Dev scripts in scripts/ may (standalone mode, D1): voice:tts (Kokoro), voice:say, write --model / try (the user's own LOCAL_LLM_*). Never put provider keys in the repo.
Layout
src/engine/lib: math (angle convention inmath.ts), easing, seeds, colorssrc/engine/rig: schema, FK skeleton (solveSkeleton), pose tracks, idle/blinks, Bézier limbs (orstyle.limbstubes for animals), accessories (animal parts inanimalParts.tsx/animalHeads.tsx),evalActor(actorState.ts: pose, expression, speech, seat, prop and symbol tracks),<Actor>src/engine/rig/seat.ts: seat track + seated-leg IK (hip on the seat, feet planted)src/engine/rig/toon/: the toon drawing tier (style.build: "toon"+ atoonblock):ToonRigon the same joints, clothes, limbs, hands, shoes, head and face.rig/build.ts:toonOf,proportionsOf(read body proportions through it),withBuild. A pose'stoonblock overrides arm angles and hands for toons only (toonPosesinactorState.ts). Guide:docs/creating-characters.mdsrc/engine/rig/shape/: the shape drawing tier (style.build: "shape"+ ashapespec): flat, outline-free figures built from part kinds on the same skeleton (ShapeRig;QuadRig+quadruped.tsforplan: "quadruped", on the biped's pose angles). Colours are tokens (palette.ts), proportions are build presets (proportions.ts),reach.tstells the camera how tall the ears are. Guide:docs/stories.mdsrc/engine/set/compose.ts:composePlace(a described place → a story-kit set). A skit or scene'splaceis composed at compile time and rides on the program (director/places.ts,Program.sets); workspacecharacters/propsride along too (withProgramAssets)src/engine/writer/story.ts/assets.ts/propPrompt.ts: the story writer prompt, the missing-asset report (near / spec / place / draw / cheat), the drawn-prop prompt. CLI:pnpm storysrc/engine/props: prop schema, per-kind drawings (draw.tsx), hold/drop track + fall (track.ts),<PropView>src/engine/face: expression schema, parametric mouths (mouths.ts), eyes/brows/mouth/symbols (Emanata.tsx: !, ?, speed lines)src/engine/face/visemes.ts: Rhubarb A–H/X → mouth params,speechMouthlayers speech on the expression mouthsrc/engine/voice: voice contract schemas,tokenize/alignWords/estimateWordsInSpanssrc/engine/text:buildCaptionPages(script tokens + timings →@remotion/captionspages),Subtitles(narrator pages italic/boxed),PovCard,SlamText,ExplainerText(title cards, list reveals; geometry inlayout.ts), safe areasrc/engine/set: set schema (withdescription/tagsfor set pickers;catalog.ts→GET /sets), palettes (tokens +derived()tones; no raw hex in parts), patterns,<SetLayers>,seatHeightAtsrc/engine/set/parts: part components by kit (room,decor,office,furniture,outdoor,street,home,venue) andregistry.ts(PART_INFO,KIT_BACKDROP). New part → add toPART_INFO; it shows up in SetLabsrc/engine/viz: figures (the science diagram layer): per-kind params (params.ts), figure + cue schema,compileFigures(states, cues, anchors, credits), frame evaluation (track.ts), real physics (physics.ts: Kepler, waves, seeded particles and dice), a safe expression language (expr.ts), drawers indraw/,<Figures>. Equations are typeset by MathJax insrc/node/equations.ts(prep), never in the engine. Guide:docs/figures.mdsrc/engine/director/explainer.ts/data.ts,src/engine/qa/variety.ts,src/engine/viz/slots.ts/paramsData.ts/map.ts: explainers (format: "explainer"): datasets and"@id.column"binding, spoken-number checks, chapters, slots, the data kinds, variety rules and fingerprints. Guide:docs/explainer.md. Long renders fan out over Lambdas (lambda/fanout.ts)src/engine/director/science.ts/scienceChecks.ts: claims, simplifications, approval hash, myth-flip roles and checks,sources.txt. Workflow:docs/science-channel.mdsrc/engine/shots/Stage.tsx: set background, back figures, actors, front figures, set foreground, under one camerasrc/engine/shots/framing.ts:frameShot({ framing, on })→ camera forwide | two | medium | close | extremesrc/engine/director: skit schema (schema.ts), diagnostics (path + expected + example), anchors, beat layout (layout.ts, inserts the punchline reaction beat), actions + listener auto-reactions → cast tracks (tracks.ts), default shot policy (shots.ts), cameras / punch-ins / shake (camera.ts),compileSkit→Timeline,<Skit>. Authoring guide:docs/skits.mdsrc/data: JSON library +index.tsloader (validates on import),safe-area.json,reactions.json(listener reaction defaults),sfx.json(SFX manifest with licenses)scripts/:sheet.ts,voice-say.ts,prep.ts,compile.ts,render.ts,sfx-gen.ts,lib/(prep, skit loading, Rhubarb + bundled ffmpeg, WAV reading,synth.tsDSP)public/skits/<id>/:skit.json(labs:script.json),voice.json,voice/*.wav(committed);generated/(gitignored)src/app: Remotion root and lab compositions (CharacterLab,FaceLab(labs takebuild: stick | toonto compare tiers;*Tooncompositions),CloseupLab,CloseupSheet,PoseLab,TalkLab,SetLab,PropLab,StagingLab,SfxLab,ContactSheet),skit/(theSkit/SkitDebugcompositions);fonts.tsloads the local text font
Rig conventions
Canonical view faces right; facing: "left" mirrors. L = back limb, R = front limb. Arms: 0° hangs along the torso, +90° forward, 180° up; elbow + flexes forward. Legs are world-relative (0° down, + forward); knee + bends back. The rig lifts the figure so the lowest foot touches groundY.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

