Jam day

A jam is where Weld earns its keep: short deadline, two people, several agents, one packaged build at the end. This is the condensed version of the runbook we use. Always check your jam’s rules for the exact deadline, time zone and submission requirements.

The day before

Fix anything red today, not on jam day.

Freeze Weld. The hub owner freezes the team on one tested version so nothing updates mid-jam. Then on every machine: weld update --yes and check weld --version.
Jam mode: weld agents jam on on every machine pauses non-critical background agents so they don’t compete for CPU and GPU.
Health: weld doctor is green on every machine (weld doctor --ai for anything left), and weld status shows node daemon running and hub online. weld ops health shows every node.
Build PC: weld node caps lists Unreal 5.8 and the GPU, weld node role list includes build, it’s plugged in, set not to sleep, with 100 GB or more free (weld cache prune if not).
GPU models in place: weld setup --roles gpu-gen reports everything already installed, so nothing downloads ~70 GB mid-jam. Smoke it: weld asset make "a wooden crate" --yes in a test project.
Template game builds: weld game new <Name> --style <preset>, weld game build, weld game smoke green, pushed to the hub.

Shipping rehearsed:

weld ship init --itch <user>/<game>       # the itch.io page can be a draft
weld ship butler --install                # on every machine that uploads
weld secret set BUTLER_API_KEY --kind shell
weld ship --channel windows --dry-run     # package → smoke → zip, no upload
weld ship --channel windows               # a real upload to the draft page

Download the build from itch.io on another machine and play it. Write down the packaging time: it sets your deadline buffer.

Video works: weld ship video prints a working ffmpeg command.
Declare your tools if the jam asks: the Weld version, template, packs and any marketplace assets.

Theme reveal

Brainstorm together, 45 minutes max, in docs/gdd.md. Each person writes three one-line pitches; vote; pick one; write the decision and why in docs/decisions.md.
Cut scope in the GDD: the core loop in one sentence, three must-haves, three nice-to-haves, and what “done” looks like for the video.
Turn the GDD into Work, one item per must-have, linked to its section:
Terminal window
```
weld work declare "Core loop: <verb>" --gdd docs/gdd.md#3-core-loop -p Source/<Name>/Core/
weld handoff "<feature>" --to <teammate> --summary "<one line>"
```
Overlaps show up straight away. Decide them now: weld overlap list, then weld overlap ack <other> --decision coordinate|proceed|pivot.
Pick the critic rubric for your style (.claude/skills/rubric-<style>/) and set modest targets with weld agents targets.
Commit, push and start Claude in the repo.

The daily rhythm

When	What
Start of day	`weld status`: handle inbox, overlaps and merges needing a human. `git pull`.
Every merge	Through the queue (`weld merge`), never a direct push. Record critic scores with `weld agents critique`.
Midday	Packaging check: `weld ship --channel windows --dry-run`. A broken package at noon is cheap; at the deadline it’s fatal.
Evening	Real upload of the day’s build (`weld ship --channel windows`); play the downloaded build for five minutes. Update the GDD’s “done” list.
End of day	`weld status` clean (no stale Work; close what’s finished), `weld ops health` green.

Keep one known-good build on itch.io at all times. Small Work items, merge often, and never leave a conflict for the next morning.

Ship it

Start the final ship at least twice your measured packaging time plus an hour before the deadline.

Code freeze. Everyone merges or parks their Work; main is the release.
Ship the Windows build (from a Mac or on the PC):
Terminal window
```
git pull
weld ship --channel windows
```
It packages Win64 Shipping on the Windows node, boot-checks the packaged game, zips it with a weld-ship.json (version, commit, config, smoke result) and uploads it with butler. If it warns that the build node packaged a different commit, pull there and ship again.
Optional Mac build: weld ship --channel mac on a Mac.
Record the gameplay video on the PC with the packaged game:
Terminal window
```
weld ship video --record --seconds 45
```
Game audio isn’t captured; add music in an editor, or use OBS when audio matters.
Publish on itch.io: set the download to the uploaded channel, add the video, screenshots and declaration, make the page public and submit it on the jam page. Then download and run it once from a private window.

When something goes wrong

What	Do this
The uploaded build is broken	itch.io keeps every upload: pick the previous one, or check out the last good commit and `weld ship --channel windows --version-label <good>-fix`.
A merge broke `main`	Revert through the queue: `git revert <sha>` on a branch, then `weld merge --branch <branch>`.
A Weld update broke a machine	`weld update --rollback` on it, and tell the hub owner.
The hub is down	Keep working: commits, builds and `weld ship --local` on the Mac don’t need it. Coordinate by chat and avoid touching the same files until it’s back.
A machine won’t connect	When things break.
The Windows PC is down	Ship the Mac build (`weld ship --channel mac`) so there’s something on itch.io, then fix the PC.