agentleFS
tamtree-aitamtree-ai/stick-stage/AGENTS.md

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

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
  1. Very specific:

    Frame-pure rendering: Every visual is a pure function of (frame, props).

    line 8
  2. Distinctive:

    Small, typed modules: No file over ~300 lines.

    line 12

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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

  1. Frame-pure rendering. Every visual is a pure function of (frame, props). No useState/useEffect for animation, no CSS animations, no Date, no Math.random(). Use seeded rand() / noise() from src/engine/lib/seed.ts.
  2. Everything is data. Characters, poses, expressions, sets, props and skits are JSON validated with zod, and every document carries schemaVersion. Components never hardcode timing.
  3. 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.
  4. Keep the engine app-agnostic. src/engine/** never calls registerRoot, never reads process.env, and never touches the filesystem. Only src/app/** and scripts/** may. (Enforced by eslint and tests/engine-rules.test.ts.)
  5. Small, typed modules. No file over ~300 lines.
  6. 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; render fine without TTS). Not pnpm setup/pnpm doctor: those are pnpm built-ins
  • pnpm try "<topic>": premise (yours, or LOCAL_LLM_*'s) → Kokoro voices → out/<id>.mp4
  • pnpm dev: Remotion Studio
  • pnpm test / pnpm typecheck / pnpm lint: run all three before every commit
  • pnpm 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 in out/
  • 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>.mp4 for public/skits/<id>/skit.json
  • pnpm render <Comp> out/x.mp4 [--frames=a-b]: any other composition (labs) passes through to remotion 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), write generated/timeline.json
  • pnpm sfx: regenerate the synthesized SFX library (public/sfx/, src/data/sfx.json); pnpm render SfxLab out/SfxLab.mp4 plays them all
  • pnpm still SetLab out/SetLab.png [--props='{"kits":["park"],"tileWidth":200}']: every set part × 3 palettes × 3 seeds
  • pnpm voice:say <skitId>: dev stand-in for the tamtree harness TTS; macOS say → public/skits/<id>/voice/ + voice.json
  • pnpm voice:tts <skitId>: the same with Kokoro in-process (or LOCAL_TTS_BASE_URL); voice map in scripts/lib/kokoro-voices.ts
  • pnpm approve <skitId> --by=<owner> [--check]: science skits: list claims, then pin the owner's sign-off to the content hash; pnpm render <skit> --post and final service renders refuse an unapproved or changed skit
  • pnpm viz:lab then pnpm 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:9
  • pnpm map:data <ne_110m_admin_0_countries.geojson>: re-bake the map figure'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, the argument style'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 in math.ts), easing, seeds, colors
  • src/engine/rig: schema, FK skeleton (solveSkeleton), pose tracks, idle/blinks, Bézier limbs (or style.limbs tubes for animals), accessories (animal parts in animalParts.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" + a toon block): ToonRig on the same joints, clothes, limbs, hands, shoes, head and face. rig/build.ts: toonOf, proportionsOf (read body proportions through it), withBuild. A pose's toon block overrides arm angles and hands for toons only (toonPoses in actorState.ts). Guide: docs/creating-characters.md
  • src/engine/rig/shape/: the shape drawing tier (style.build: "shape" + a shape spec): flat, outline-free figures built from part kinds on the same skeleton (ShapeRig; QuadRig + quadruped.ts for plan: "quadruped", on the biped's pose angles). Colours are tokens (palette.ts), proportions are build presets (proportions.ts), reach.ts tells the camera how tall the ears are. Guide: docs/stories.md
  • src/engine/set/compose.ts: composePlace (a described place → a story-kit set). A skit or scene's place is composed at compile time and rides on the program (director/places.ts, Program.sets); workspace characters / props ride 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 story
  • src/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, speechMouth layers speech on the expression mouth
  • src/engine/voice: voice contract schemas, tokenize / alignWords / estimateWordsInSpans
  • src/engine/text: buildCaptionPages (script tokens + timings → @remotion/captions pages), Subtitles (narrator pages italic/boxed), PovCard, SlamText, ExplainerText (title cards, list reveals; geometry in layout.ts), safe area
  • src/engine/set: set schema (with description / tags for set pickers; catalog.ts → GET /sets), palettes (tokens + derived() tones; no raw hex in parts), patterns, <SetLayers>, seatHeightAt
  • src/engine/set/parts: part components by kit (room, decor, office, furniture, outdoor, street, home, venue) and registry.ts (PART_INFO, KIT_BACKDROP). New part → add to PART_INFO; it shows up in SetLab
  • src/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 in draw/, <Figures>. Equations are typeset by MathJax in src/node/equations.ts (prep), never in the engine. Guide: docs/figures.md
  • src/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.md
  • src/engine/shots/Stage.tsx: set background, back figures, actors, front figures, set foreground, under one camera
  • src/engine/shots/framing.ts: frameShot({ framing, on }) → camera for wide | two | medium | close | extreme
  • src/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.md
  • src/data: JSON library + index.ts loader (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.ts DSP)
  • 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 take build: stick | toon to compare tiers; *Toon compositions), CloseupLab, CloseupSheet, PoseLab, TalkLab, SetLab, PropLab, StagingLab, SfxLab, ContactSheet), skit/ (the Skit / SkitDebug compositions); fonts.ts loads 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.