t1k:unity:sexygame:template-sync
| Field | Value |
|---|---|
| Module | sexygame |
| Version | 1.7.2 |
| Effort | high |
| Tools | — |
Keywords: backport to template, đồng bộ template, migrate legacy sgame skills, pull template changes, sync template
How to invoke
Section titled “How to invoke”/t1k:unity:sexygame:template-synct1k-unity-sexygame-template-sync — pull template changes in, backport game fixes out
Section titled “t1k-unity-sexygame-template-sync — pull template changes in, backport game fixes out”The agent-facing procedure around one deterministic tool, stp_template_sync.py (stdlib python, no AI, no network beyond git). This skill adds no
logic of its own: it says WHEN to run each mode, how to read the answer, and what to do next. Engine and ownership rules:
t1k-unity-sexygame-template-setup §6 (../t1k-unity-sexygame-template-setup/SKILL.md) and sync-mode (../t1k-unity-sexygame-template-setup/references/sync-mode.md).
<RepoRoot> = the game’s git root. <SetupDir> = .claude/skills/t1k-unity-sexygame-template-setup (installed from the kit module sexygame; user scope ~/.claude/skills/... works too). <Tool> = python3 <SetupDir>/scripts/stp_template_sync.py.
<TemplateClone> = a clone of The1Studio/SgameTemplate (never inside the game). <TemplateWt> = a template worktree for a backport.
Paths in tool output use {U} for the Unity project folder (UnitySgameNutSort/ in NutSort), so the same row names the same file in both repos.
Every command below is non-interactive, prints a table or one summary line, and ends with a stable exit code (exit codes (references/exit-codes.md)).
pull, backport and baseline are DRY RUNS until --apply. Errors name the fix; follow the message.
Step 0 - preflight (read-only, 4 checks)
Section titled “Step 0 - preflight (read-only, 4 checks)”| # | Check | Command | Stop when |
|---|---|---|---|
| 0.1 | this is a template-derived repo with the CURRENT kit module | ls <RepoRoot>/.claude/sgame-template/ownership.json; the Unity folder has Assets/Scripts/Editor/TemplateSetup/; <SetupDir>/scripts/stp_template_sync.py exists; stp-verify.py modules exits 0 (installed AND latest); <RepoRoot>/.claude/sgame-setup/template-sync.json may exist | no TemplateSetup/ folder: not a derivative. Module missing or older: t1k modules update (or run python3 .claude/sgame-template/bootstrap.py). Legacy sgame-* skill dirs still present: migration (references/migration-from-legacy-skills.md) |
| 0.2 | the template clone is fresh | git -C <TemplateClone> fetch origin master then git -C <TemplateClone> merge-base --is-ancestor origin/master HEAD | exit 1 here, or the tool exits 4: tell the user, run git -C <TemplateClone> pull --ff-only origin master, or skip the clone and pass --template-ref github:The1Studio/SgameTemplate@master |
| 0.3 | the game tree is clean enough | git -C <RepoRoot> status --porcelain | a dirty path that a pull would overwrite (a template-owned file): commit your own paths first with a pathspec commit; never git stash (shared stack) |
| 0.4 | you are not in the template itself | git -C <RepoRoot> remote get-url origin | it is SgameTemplate: the tool exits 2 (“same repository”); pass --game <game repo> |
A template source is always one of: --template <TemplateClone> or --template-ref github:The1Studio/SgameTemplate@master. Add --game <RepoRoot> when your cwd is not inside the game.
Step 1 - see what differs (read-only)
Section titled “Step 1 - see what differs (read-only)”python3 .claude/skills/t1k-unity-sexygame-template-setup/scripts/stp_template_sync.py check --template-ref github:The1Studio/SgameTemplate@masterpython3 .claude/skills/t1k-unity-sexygame-template-setup/scripts/stp_template_sync.py diff --template-ref github:The1Studio/SgameTemplate@masterpython3 .claude/skills/t1k-unity-sexygame-template-setup/scripts/stp_template_sync.py diff --template-ref github:The1Studio/SgameTemplate@master --json --allcheck is one line (PASS|FAIL template-sync: pull=2, ...) and the exit code. diff prints class | path | template sha | game sha | action; --all adds the quiet rows.
Read the class column (ownership classes (references/ownership-classes.md)):
| Class | Meaning | You do |
|---|---|---|
same / diverged-ok / game-only | nothing to sync | nothing |
pull | only the template changed (or a new template file) | Step 2 |
backport | only the game changed a template-owned file | Step 5 (or revert the game edit if it was an accident) |
game-edit-already-in-template | both changed, but the template already contains the game’s edit | pull --apply takes the template (default action; nothing is lost) |
conflict | both changed, or there is no baseline entry | Step 3 |
unregistered | a file under a scan root no ownership rule covers | the registry is incomplete: STOP, tell the user (registry-lint names it); do not guess an owner |
Step 2 - pull (template-owned files only)
Section titled “Step 2 - pull (template-owned files only)”python3 .claude/skills/t1k-unity-sexygame-template-setup/scripts/stp_template_sync.py pull --template-ref github:The1Studio/SgameTemplate@master --dry-runpython3 .claude/skills/t1k-unity-sexygame-template-setup/scripts/stp_template_sync.py pull --template-ref github:The1Studio/SgameTemplate@master --applypullclassifies with the TEMPLATE’s.claude/sgame-template/ownership.jsonwhen it differs (it printsregistry: classifying with ...), so a game with an older registry can--take-templatenewly registered paths in the same invocation; no separate registry pull first.- Run the dry run, show the user the
WOULD copy|removelines and everyCONFLICTdiff. Wait for a yes when the list touches anything outside.claude/skills/and{U}/docs. --applywrites onlytemplateandmixedrows. Game-owned files (answers, state, owner decisions, blueprints) and the game regions of mixed files (stp:fact,stp:gen,stp:identity,stp:ledger-*) are untouched.- Frozen submodule pointers are not synced here. The seven frozen submodules (
Assets/TheOneFeature, …) are bumped upstream-first, in the template, then in the game as a separate commit with the owner’s yes (pins (../t1k-unity-sexygame-template-setup/references/pins.md)). - A seed file the game deleted on purpose (placeholder art,
Placeholder/Boosters/*) readspullforever. Record it:... stp_template_sync.py tombstone '<{U}/path or glob>' --reason "<why>" --apply(orpull --apply --skip-seed <path>); pull then never copies it back andcheckignores the row.--keep-gamedoes not apply to seeds. --applyrewrites.claude/sgame-setup/template-sync.json(the 3-way baseline) with the template commit it synced to. Exit 0 = nothing left; exit 1 = conflicts remain (they were not written).
Step 3 - conflicts (never auto-resolved, never overwrite game-owned content)
Section titled “Step 3 - conflicts (never auto-resolved, never overwrite game-owned content)”For each conflict row: show both sides (the CONFLICT block is a unified diff, template vs game), then decide by the rule’s class:
| Situation | Decision | Command |
|---|---|---|
file is class template, the game edit is an accident or already in the template | take the template | --take-template <{U}/path> |
file is class template, the game edit is a real fix and not game-specific | keep it now, backport it (Step 5) | --keep-game <path>, then Step 5 |
file is class template, the game edit is game-specific | the file is wrongly owned: do not force it; tell the user and propose an ownership rule change in the template (.claude/sgame-template/ownership.json) | --keep-game <path> meanwhile |
file is class mixed | the skeleton conflicts; the marker regions are the game’s and stay | --take-template writes the template skeleton and keeps the game regions |
no baseline entry (game never adopted) | the tool cannot tell who moved | Step 6, never --take-template blind on files the game may have tuned |
--take-template / --keep-game take the {U}/... path exactly as printed (or the plain <unity folder>/... form), repeat per file, and only apply to class template or mixed. --keep-game records the
choice with both shas in the baseline, so the row stays diverged-ok until the GAME file changes again or you re-choose; a later template change to it is shown in the row’s action (the template changed since the choice), never as a new conflict. Record why in the commit message (Step 4); the owner-directed
changes of the game go in .claude/sgame-setup/owner-decisions.md (game-owned); the template-wide ones live in t1k-unity-sexygame-template-setup/references/owner-decisions.md (kit-owned, changed by a kit PR).
Step 3b - a mixed file with no markers (after --keep-game or an old game)
Section titled “Step 3b - a mixed file with no markers (after --keep-game or an old game)”A game’s CLAUDE.md, {U}/CLAUDE.md, Placeholder/README.md and docs may lack the stp: regions, so the skeleton drifts and the identity, ledger and fact apply have nowhere to write.
python3 .claude/skills/t1k-unity-sexygame-template-setup/scripts/stp_template_sync.py insert-markers [<{U}/path or glob>] --template-ref github:The1Studio/SgameTemplate@master (dry run) then --apply
wraps the game’s own text in the template’s regions; the prose is never rewritten. A SKIP line names a region with no anchor in the game text: add that one by hand. Idempotent; existing regions are untouched.
Step 4 - verify, baseline, commit
Section titled “Step 4 - verify, baseline, commit”In a fresh linked worktree the frozen submodules are empty; do NOT git submodule update --init (9+ minutes). Reuse the main clone’s copy first (seconds, same commit only, invisible to git):
python3 .claude/skills/t1k-unity-sexygame-template-setup/scripts/stp_worktree_submodules.py link --project <UnityProjectRoot> (clear undoes it).
python3 .claude/skills/t1k-unity-sexygame-template-setup/scripts/stp-verify.py all --project <UnityProjectRoot> --mode gamepython3 .claude/skills/t1k-unity-sexygame-template-setup/scripts/stp_template_sync.py check --template-ref github:The1Studio/SgameTemplate@master- The setup skill’s own tests (
tests/run.py) are TEMPLATE-side only: do not run them in the game. stp-verify.py all --mode gamegreen (exit 0) = every game gate holds with the newly pulled gates; a FAIL row is either a real gap the new template gate found (fix it in the game, or backport if it is not game-specific) or a new cost-A answer the gate wants (stp_interview.py next). Never edit the pulled gate to turn it green. A red you did not cause (it fails the same way on the commit before your pull): record it, do not hide it.checkmust printPASS(conflicts kept with--keep-gamecount asdiverged-ok). The baseline was already updated bypull --apply; do not hand-edit it.- Skill data is vendored, not read from
~/.claude. The Editor preflight reads.claude/skills/t1k-unity-sexygame-template-setup/data/from the repo root; the skill installs at user scope, so a clean CI checkout lacks it and the Release build dies with[Template Setup] BUILD FAILED.pull --apply(andstp_template_sync.py vendor-data --apply) copiesdata/byte-for-byte into the game and writesdata/.vendored.json;checkfails on any drift; theskill-data-vendoredgate fails when the probe’s path is absent from the committed tree. Aftert1k modules updatere-runvendor-data --applyand commit.claude/skills/t1k-unity-sexygame-template-setup/data. - Commit pathspec-only, naming the template commit (the
templateCommitintemplate-sync.json, or the@ <sha>the tool printed):
git -C <RepoRoot> commit -m "chore(template): sync from SgameTemplate @ <template-sha>" -- .claude/skills .claude/sgame-setup/template-sync.json <UnityDir>/docs <UnityDir>/Assets/Scripts/Editor/TemplateSetupList the exact changed paths, never git add -A. Keep the pull and any gate fixes in separate commits.
Step 5 - backport game fixes to the template
Section titled “Step 5 - backport game fixes to the template”Process rule (setup §6 (../t1k-unity-sexygame-template-setup/SKILL.md)): every non-game-specific fix is backported in the SAME session, as a PR, tracked as a task.
- Make a template worktree (never edit the template’s main clone):
git -C <TemplateClone> fetch originthengit -C <TemplateClone> worktree add <TemplateWt> -b backport-wip origin/master. python3 .claude/skills/t1k-unity-sexygame-template-setup/scripts/stp_template_sync.py backport --template <TemplateClone> --to <TemplateWt>(dry run: listsWOULD COPYfiles, the branchbackport/<game>-<date>, the PR checklist).- Ask: is each file really not game-specific? A game-specific change is reverted in the game or
--keep-gamed, not backported. ... backport --template <TemplateClone> --to <TemplateWt> --applycreates the branch, copies the files (mixed files: skeleton only, the template’s own regions kept). The worktree must be clean (exit 2 otherwise).- Create ONE task per backported file (the tool prints
TaskCreate: backport <path> ...lines). Review the diff in<TemplateWt>, run the template’s tests for the touched area (tests/run.py <lane>), commit there with a pathspec, push, open the PR against the template’s default branch. Record a fixed failure withstp-failures.py add. - Until the PR merges the row stays
backport; after it merges, Step 1 showssame. Do not--keep-gamea backport candidate to silence it.
Step 6 - first-time adoption and bootstrap
Section titled “Step 6 - first-time adoption and bootstrap”Game created before the baseline existed (no .claude/sgame-setup/template-sync.json): every differing template file reads conflict (no baseline entry).
- Game is known to match the template for the files you care about:
baseline --adopt(dry run), then--adopt --apply. Caution:--adoptrecords the template’s CURRENT shas as “assumed equal”, so a file the game has that is older than the template then reads as a game edit (backport), and a real game edit as well. Adopt only right after a pull, or whendiff --allshows the template filessame. - Old game that lags the template: do NOT adopt first. Run
diff, pick the template-owned rows the game never edited (the skill dir, TemplateSetup, docs), and take them:pull --apply --take-template <path> ...(this also writes the first baseline). Game-tuned files:--keep-game. - Show the baseline with
baseline --show(printsno baselinewhen absent).
Bootstrap (the repo has no kit skill yet, or only the legacy sgame-* dirs): the tool is KIT-owned now, so it is never copied from the template. In the game repo root: t1k modules update (installs/updates sexygame with this skill), then python3 <SetupDir>/scripts/stp_template_sync.py vendor-data --apply (commit the vendored data/), then python3 .claude/skills/t1k-unity-sexygame-template-sync/../t1k-unity-sexygame-template-setup/scripts/stp_template_sync.py diff --template-ref github:The1Studio/SgameTemplate@master. A game that predates this move follows migration (references/migration-from-legacy-skills.md) first.
Step 7 - self-update
Section titled “Step 7 - self-update”This skill and the setup skill are kit content, updated by t1k modules update (the template’s bootstrap.py and stp-verify.py modules force it), never by pull. pull moves only what the template owns: the Unity project files, docs and .claude/sgame-template/ (the ownership registry and the bootstrap).
After t1k modules update changed this skill, re-read this file: the procedure you just followed may have changed.
- Never overwrite game-owned content, never edit a game’s
answers.jsonortemplate-sync.jsonby hand, nevergit stash, never--no-fetchto dodge exit 4. - Never edit
.claudefiles owned by the T1K kit (everything under.claude/skills/and.claude/modules/comes fromt1k modules update, never from the template; onlysgame-setup/andsgame-template/are the game’s / the template’s). - Never run the tool against the template as
--game; never sync the frozen submodule pointers here.
More: migration from the legacy skills (references/migration-from-legacy-skills.md) · gotchas (references/hard-rules.md) · worked example: NutSort (references/worked-example-nutsort.md) · exit codes (references/exit-codes.md) · ownership classes (references/ownership-classes.md).