Workflow Ship Change

Workflow: ship a change

A change is done only when all of these are true, and the report shows each one:

1. Screenshots of the real rendered game: the start state, the key moment and the result. They're shown inline in the report.
2. Its own changelog version, with its pictures on the in-game changelog page.
3. Verified:
   • your own tests;
   • the tests of commits you merged in;
   • the asset checks;
   • the full suite, run on the pushed commit.
4. Committed: one cohesive commit, with only your own files staged.
5. Pushed to main as a fast-forward, and confirmed on GitHub.
6. Live: the build of that exact main is published, and confirmed working on the real domain.
7. Measured: the sizes of the commit, the push, any upload and the publish, all measured, never estimated.

Pushing and publishing are standing authorizations for the project's own repository and live site. So don't ask before them, except where a guardrail below says stop. Read the project's AGENTS.md before starting, and this skill's references/<project>.md if there is one. Project rules change often, and wherever they differ from this skill, they win.

Guardrails: stop and ask the user

• Any upload over 50 MB. That covers a git push, a Netlify deploy, a media release, and files sent to any outside service.
  • Measure first (upload-size.sh, or the pack size push-main.sh prints), and state the size when asking.
  • Count the whole operation, and never split it to get under.
  • A full Supabase media release (about 861 MiB) always needs asking.
• A force-push, rewriting remote history, changing repository visibility, or pushing to another repository.
• A new site or project, or changing a site's access, domain or DNS, unless the task is exactly that and the user asked for it.
• When the permission check blocks a deploy, rollback or upload: stop. Don't retry it another way or through another thread. Tell the user the exact click path or command.
• Live broken after your publish: say so first in your report, with the measured evidence and the rollback click path. Don't bury it.

Guardrails: never

• Never publish anything but the clean, pushed origin/main. No unmerged branch, no uncommitted file.
• Never deploy large media to Netlify as a fallback; media lives in Supabase Storage.
• Never publish to a host the project has retired, even if old scripts still point at it.
• Never run the broad image optimizer (pnpm images:optimize, or optimize-images.py --apply). It rewrites other sessions' pending images. Use runtime-assets.py --only '<your glob>', then --verify.
• Never stage credentials, .env*, node_modules, caches or build output, and never use git add -A in a shared checkout.
• Never call a local commit pushed, or a deploy live, until you've confirmed it on the remote or the domain.
• Never kill a process you didn't start. Check its working folder first: lsof -a -p <pid> -d cwd.

Steps

0. Before you start

• Run git fetch, then git log origin/main --oneline -30, and search for your area. Look in the sibling worktrees (git -C <wt> diff --stat) for someone already making the same edit.
• Work in your own worktree on a branch off origin/main. Other sessions edit the shared checkout live.

1. Screenshots

• Capture the real game at 1600×900 using the project's review fixtures (?review=<name>). Take the start, the key moment and the result.
• If the project names a capture tool, use it. Otherwise capture headlessly over CDP (see the workflow-progress-screenshots skill), and say which you used.
• Look at every picture before using it. Stray toasts, stale numbers, or the wrong scene mean recapture.
• Label them honestly: headless browser captures, and a phone-sized viewport is not a device test.
• Keep capture scripts in the worktree's gitignored qa/captures/; the session scratchpad is wiped on restart.

2. Changelog version

• Follow the project's changelog rules exactly: format, versioning, and how pictures are added.
• Write for players: what they can see or do now, with no file names or hashes.
• Changes to tests, tooling, docs or rules get no version.
• If another session took your version number, renumber yours on merge, and keep their entries.