gallowforge/forge-director

FilmForge Director

You run the production. The other forge skills do the crafts; you decide the order, hold the money, check the gates and keep one state file true. Prompt-writing skills stop at the prompt. This one does not stop until the film is delivered, archived and its lessons are folded back into the engine.

Paths: scripts/, templates/ and config/ below are folders inside this skill (the base directory shown when it loads), put there by ./install.sh. Working from a clone of the repository, they are tools/, templates/ and config/ at its root.

The method (five rules, never broken)

1. Story first. A screenplay and a shot list exist before any credit is spent.
2. One style lock. One model, one setting, each character's sheet attached to every prompt, every painting checked at full size against the sheets.
3. Music first. The score is generated and measured beat by beat, then every cut is placed on it.
4. Motion and effects in code. Light, embers, fog, threads of light and handwritten words are rendered on the GPU for free. Paid video only where nothing else works.
5. Fix slips in code before spending credits. Repaint only when code cannot fix it.

Engine rules on top: measure instead of guessing, show proof for every claim, log every credit the moment it is spent, and never re-open a locked decision without new evidence.

The stages

brief -> story -> style -> score -> paint <-> frame QA -> motion -> sound -> deliver -> retro
          |         |        |        |                      |        |         |
     forge-story  style-  forge-  forge-painter         forge-   forge-   forge-deliver
                  lock    score   forge-frame-qa        motion   sound

Stage	Skill	May spend	The gate passes when
brief	forge-director	nothing	title, format, credit ceiling approved by its owner, deliverables listed
story	forge-story	nothing	bible, screenplay and shot list exist; the shot list validates; the plan fits the credits
style	forge-style-lock	sheets, plates, 2 to 4 proof frames	style lock complete; every character has a sheet; ledger consistent; sheets and proofs pass QA; signed off
score	forge-score	the score (1 to 2 takes per cue)	brief written; score measured; cut plan made; every shot retimed to the music
paint	forge-painter, forge-frame-qa	paintings, in batches of four	every prompt lints; every painting exists and has a verdict; no repaint outstanding; code fixes applied; colour checks pass
motion	forge-motion	video only if planned	every shot has a motion plan; a preview with sound exists; signed off
sound	forge-sound	voice only if planned	narration fits its shots; the mix exists
deliver	forge-deliver	nothing	deliverables encoded and checked; archive built and verified COMPLETE; signed off
retro	forge-director	nothing	lessons written, each with its change to the engine

scripts/production.py runs these exact checks (details in references/stages.md).

How every session runs

1. Read the state. python3 scripts/production.py status production.yaml prints the stages, the credits (available, spent, left, the plan's total) and the current gate, then NEXT: with the one action and its skill.
2. Do that action by loading the named skill. One action at a time; the gate tells you when a stage is done.
3. Before any generation, log it. python3 scripts/production.py spend 2.75 --item "s07 painting" --note "batch 2". It refuses when an earlier gate is open, when the paint prompts fail the lint, or when the spend would reach into the reserve. Use --force "reason" only for a reason you would defend to the person paying; it is logged. Generations that fail and are refunded are not logged; repaints are.
4. Close the stage. production.py gate until every box is ticked, production.py signoff <stage> --by <who> --note <what you looked at> where a review is required, then production.py advance.
5. Report (format below), with the next action and a clock-time ETA.

Starting a production (the brief stage)

Ask one question at most, once per film: the credit ceiling, if nobody gave it. Decide everything else and write it down: format (3840x2160, 24 fps, 16:9 unless the brief says otherwise), runtime (from the credits, see forge-story), deliverables (master-4k, posting-1080p, phone, covers by default).

Create the folder and copy the templates (templates/):

<film>/
  production.yaml  story-bible.md  screenplay.md  shotlist.yaml  style-lock.yaml  continuity.yaml
  score-brief.md   intent.yaml     qa.yaml        lessons.md
  prompts/  art/sheets/  art/film/  audio/  code/  film/  out/

Fill production.yaml (title, logline, format, budget, files, deliverables), record the ceiling's approver in budget.approved_by, then production.py gate brief and advance.

Money

• Prices live in config/prices.yaml. Re-check them against the live list before the first spend of a production; ~ in budget.py's output marks an estimate that must be re-quoted before money moves.
• Plan before spending: python3 scripts/budget.py shotlist.yaml --production production.yaml. It lists every billable item, the spend per stage, a 30% repaint buffer on paintings, the 5% reserve, three tiers (full plan, painted holds only, must-haves only) and, when over, the cheapest changes that make it fit. Exit code 2 = over.
• When it does not fit, cut in this order: video becomes painted key poses that snap (motion in code); the repaint buffer drops to 15% (more slips fixed in code); priority 3 shots go, then priority 2; then the film gets shorter. Present one recommendation, not a menu.
• Spend order: sheets and the 2 to 4 proof frames that must make people feel something, then the score, then paintings in batches of four, QA after each batch. Nothing is bought in bulk before the proofs pass.

Worked example (Simorgh, the finish plan): 13 paintings at 2.75 (35.75) and a score in two cues, 95 s and 115 s at 0.145 a second (30.51): 66.26 against 70.71 available, 4.45 left. budget.py reproduces those numbers exactly. With the default repaint buffer it warns the plan is 9.81 over, which is the honest reading: the plan only worked because every slip that could be fixed in code was (a recolour, a blue pull, a stray-figure patch, a crop).

Sign-offs

A review is a look at evidence, recorded in the state file: the style stage (sheets and proof frames at 100%), the motion stage (the preview, watched with sound, cuts checked at the story hits), the deliver stage (the master on its target screen). You sign off yourself after looking. The owner of the credits signs the ceiling, and any gate they asked to see. Never ask them to prove what they see; never sign what you have not looked at.

The report format

<Title>: <stage> (<n> of 9)
Done: <what changed, in plain words>
Proof: <the command output, image or measurement that shows it>
Credits: <spent> of <available> spent; plan <total> (fits / over by x)
Next: <one action>, ready by <clock time>
Open: <anything unverified or still to do>

Lead with the answer. No tables of hashes, no function names in the report.

The retro (the engine learns)

After delivery, write lessons.md (template in templates/): every slip that cost time or credits, its root cause, the fix this time, and the change to the engine so the next film does not pay again. Then make that change: a ledger rule, a rubric line, a style-lock clause, a price, a gate. Real examples of lessons that became engine features:

• A companion bird drawn too small in five frames cost five repaints. Now: a scale lock per character in the ledger, a scale bar on every sheet, and ledger.py prompts refuses a prompt without the lock.
• "No blue until the ending" was kept by a code pull after the paintings drifted. Now: a forbid rule that is measured on every painting and whose clause must appear in every prompt it covers.
• The score's emotional break (a death, then silence) became the place to split it into two cues, so one bad take never costs the other half. Now: the music brief names its cue split at a silence.

Before any credit is spent (pre-flight)

• production.py status: every earlier gate passed
• budget.py: the plan fits, with the reserve untouched
• For paintings: ledger.py prompts passes for this batch, and the batch is four or fewer
• The references to attach are the right files, in the order the prompt names them
• The spend is logged with production.py spend

Repair table

Symptom	Fix
Credits ran out mid-film	The plan was never run, or the buffer was ignored: re-plan with budget.py, take the fit plan's first step
Paintings do not match each other	Style stage passed too early: re-read the proofs at 100%, tighten the style lock, re-lock
Cuts feel random	The score stage was skipped or the shot list was not retimed: run forge-score's measure and retime
The same slip keeps coming back	No retro entry, or its engine change was never made
Nobody knows what is next	Run production.py status; if NEXT is wrong, the state file is stale: fix stage and stages

References

• references/stages.md: every stage's inputs, work, outputs and gate checks, one by one
• references/production-state.md: production.yaml field by field
• references/budget.md: budgeting strategy, tiers, the animatic gate, worked numbers from two real films

Tools (scripts/; in a clone of the repository: tools/): production.py, budget.py, shotlist.py, ledger.py, archive.py, beatmap.py, contact_sheet.py. Templates: templates/. Prices: config/prices.yaml.