/git-story-film

name: git-story-film
description: Direct an animated film of about two minutes from a software repository's Git history. Select real commits, releases and reverts; develop the story, character and visual style; build an outline, cast sheet, storyboard and HTML review studio; then render a 4K/60fps MP4 after approval. Use for repository or product promos, launches, anniversaries, release stories, codebase timelines, character-led project histories, and requests such as "make a video about our project" or "show how this product grew." Not for UI screen recordings, slide decks, or commit-statistics charts.

Git story film

The user gives you a GitHub link. You direct a film of about two minutes on how that product grew up. The git history is the footage: it supplies the order, the dates and the proof. Your job is to turn it into a story a newcomer enjoys and learns from: what the product is, how it got here, what it can do for them.

Directing means you make the calls and show them, and the user approves. You own three things:

• **Data.** Which facts carry the film. Out of thousands of commits, pick

the first commit, the release, the busiest day, the reverts and the hero feature, and put real hashes, dates and counts on screen. Everything shown is true and sourced; illustrative numbers are marked.

• **Story.** The protagonist, whose voice the captions are, the form the

growth takes on screen, and the arc: setup (the first commit, the problem) → development (abilities arrive) → turning point (the revert, the rewrite, the busiest day) → resolution (where it landed, and what it means for the viewer).

• **Look.** The art style and how it changes: a look per act with a story

reason, the palette, the protagonist's design, type and sound.

A mascot hatching and walking along the timeline is one form, not the only one. The same growth can be staged as something growing in place, a machine being built, game levels, a user's days, or a form the product suggests (`references/forms.md`). Choose for each product.

The engine in `engine/` (MIT, adapted from alesha-pro/tools hand-drawn-canvas-animation, https://github.com/alesha-pro/tools/tree/main/skills/hand-drawn-canvas-animation; keep its LICENSE with it) draws and animates, and `engine/studio-ui.js` turns any film page into the review studio. `examples/raven-story/` is a finished journey film (128 s, made for EverMind's Raven, with Chinese files in `zh/`). Reuse their code; do not start from a blank page.

The instructions and default examples use English. Keep dedicated Chinese film assets in `zh/` and Chinese UI labels as localization data; translating those into English would remove the Chinese cut. Choose the output language for the audience, and use `--ui zh` only for a Chinese storyboard interface.

Setup

Clone the repo outside the film folder (`git clone --filter=blob:none <url>`) and research it before step 1: run `python3 scripts/git_timeline.py <repo>`, read the README feature list and docs, and note the first commit, public release, busiest day, reverts, hero feature, built-in agents/modules and real integrations (`references/story.md` §1, §6). Ask about audience, languages and where the film will be shown if you don't know.

Set up the film folder, also outside the product repo (`references/production.md` §1):

• copy `engine/*`, `scripts/render-hq.mjs` and `scripts/frames.mjs`;
• run `npm i` and `sh scripts/fetch_fonts.sh <dir>`;
• run `git init` with `node_modules/` and `out/` ignored.

For a journey, start from the example. For a Chinese film take `raven-cast.js`, `raven-world.js`, `raven-route.js` and `raven-flight.js` from `examples/raven-story/zh/`, and the rest (`raven.html`, `raven-score.js`, `cast-sheet.html`) from `examples/raven-story/`; for English take everything from the top level. For another form, keep the example's film HTML, writer and score as the skeleton and write the world code fresh. Every film HTML loads `studio-ui.js` right after `core.js`. The bundled example links to `../../engine/`; when copying it into a flat film folder with the engine, change those script paths to the local filenames.

Captions carry the voice and the score is synthesized; there is no voiceover. If the user asks for voiceover, say so and offer to leave timed caption gaps for a recorded track.

The director's workflow

Seven steps, in this order. Each ends with something the user can look at, and you stop for their approval before the next. Story, character and pacing are cheap to change on paper and expensive after a 4K render. Templates, shot fields and checks are in `references/directing.md`.

1. **Outline: story direction.** Tell the user what story you'll tell and what it highlights. Start `OUTLINE.md` with a logline, the form and why it fits, the protagonist and caption voice, the four-part story arc in four lines, the 3–5 things the film will make the viewer remember (and which gets the most time), the numbers it stands on, and the look in a line or two. 2. **Character: expressions and actions.** Design the protagonist (and companions) in the chosen look. Render `cast-sheet.html` with 6–12 expressions, key poses for each action the story needs (walk or hop cycle, jump, fly, talk, point, carry), every material they appear in, and a 1×/2×/3× size check (`references/craft.md` §1–2, §8). 3. **Outline: the full film.** Expand `OUTLINE.md` to the whole film, about 2:00: acts and looks with reasons, recurring devices, one line per beat (time, what happens, feature, commit), the ending, and claims to double-check. 4. **Storyboard: the first 30 seconds.** Write the shots for the first 30 seconds into `shots.json`, draw one keyframe per shot with the real cast and world code, and open the storyboard page: `python3 scripts/storyboard.py shots.json --frames storyboard/frames --out storyboard/storyboard.html --ui en`. These 30 seconds fix the tone, pacing, voice and look for t