Skip to content

t1k:unity:sexygame:template-sync

FieldValue
Modulesexygame
Version1.7.2
Efforthigh
Tools—

Keywords: backport to template, đồng bộ template, migrate legacy sgame skills, pull template changes, sync template

/t1k:unity:sexygame:template-sync

t1k-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.

#CheckCommandStop when
0.1this is a template-derived repo with the CURRENT kit modulels <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 existno 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.2the template clone is freshgit -C <TemplateClone> fetch origin master then git -C <TemplateClone> merge-base --is-ancestor origin/master HEADexit 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.3the game tree is clean enoughgit -C <RepoRoot> status --porcelaina 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.4you are not in the template itselfgit -C <RepoRoot> remote get-url originit 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.

Terminal window
python3 .claude/skills/t1k-unity-sexygame-template-setup/scripts/stp_template_sync.py check --template-ref github:The1Studio/SgameTemplate@master
python3 .claude/skills/t1k-unity-sexygame-template-setup/scripts/stp_template_sync.py diff --template-ref github:The1Studio/SgameTemplate@master
python3 .claude/skills/t1k-unity-sexygame-template-setup/scripts/stp_template_sync.py diff --template-ref github:The1Studio/SgameTemplate@master --json --all

check 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)):

ClassMeaningYou do
same / diverged-ok / game-onlynothing to syncnothing
pullonly the template changed (or a new template file)Step 2
backportonly the game changed a template-owned fileStep 5 (or revert the game edit if it was an accident)
game-edit-already-in-templateboth changed, but the template already contains the game’s editpull --apply takes the template (default action; nothing is lost)
conflictboth changed, or there is no baseline entryStep 3
unregistereda file under a scan root no ownership rule coversthe registry is incomplete: STOP, tell the user (registry-lint names it); do not guess an owner
Terminal window
python3 .claude/skills/t1k-unity-sexygame-template-setup/scripts/stp_template_sync.py pull --template-ref github:The1Studio/SgameTemplate@master --dry-run
python3 .claude/skills/t1k-unity-sexygame-template-setup/scripts/stp_template_sync.py pull --template-ref github:The1Studio/SgameTemplate@master --apply
  1. pull classifies with the TEMPLATE’s .claude/sgame-template/ownership.json when it differs (it prints registry: classifying with ...), so a game with an older registry can --take-template newly registered paths in the same invocation; no separate registry pull first.
  2. Run the dry run, show the user the WOULD copy|remove lines and every CONFLICT diff. Wait for a yes when the list touches anything outside .claude/skills/ and {U}/docs.
  3. --apply writes only template and mixed rows. 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.
  4. 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)).
  5. A seed file the game deleted on purpose (placeholder art, Placeholder/Boosters/*) reads pull forever. Record it: ... stp_template_sync.py tombstone '<{U}/path or glob>' --reason "<why>" --apply (or pull --apply --skip-seed <path>); pull then never copies it back and check ignores the row. --keep-game does not apply to seeds.
  6. --apply rewrites .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:

SituationDecisionCommand
file is class template, the game edit is an accident or already in the templatetake the template--take-template <{U}/path>
file is class template, the game edit is a real fix and not game-specifickeep it now, backport it (Step 5)--keep-game <path>, then Step 5
file is class template, the game edit is game-specificthe 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 mixedthe 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 movedStep 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.

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).

Terminal window
python3 .claude/skills/t1k-unity-sexygame-template-setup/scripts/stp-verify.py all --project <UnityProjectRoot> --mode game
python3 .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 game green (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.
  • check must print PASS (conflicts kept with --keep-game count as diverged-ok). The baseline was already updated by pull --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 (and stp_template_sync.py vendor-data --apply) copies data/ byte-for-byte into the game and writes data/.vendored.json; check fails on any drift; the skill-data-vendored gate fails when the probe’s path is absent from the committed tree. After t1k modules update re-run vendor-data --apply and commit .claude/skills/t1k-unity-sexygame-template-setup/data.
  • Commit pathspec-only, naming the template commit (the templateCommit in template-sync.json, or the @ <sha> the tool printed):
Terminal window
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/TemplateSetup

List 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.

  1. Make a template worktree (never edit the template’s main clone): git -C <TemplateClone> fetch origin then git -C <TemplateClone> worktree add <TemplateWt> -b backport-wip origin/master.
  2. python3 .claude/skills/t1k-unity-sexygame-template-setup/scripts/stp_template_sync.py backport --template <TemplateClone> --to <TemplateWt> (dry run: lists WOULD COPY files, the branch backport/<game>-<date>, the PR checklist).
  3. Ask: is each file really not game-specific? A game-specific change is reverted in the game or --keep-gamed, not backported.
  4. ... backport --template <TemplateClone> --to <TemplateWt> --apply creates the branch, copies the files (mixed files: skeleton only, the template’s own regions kept). The worktree must be clean (exit 2 otherwise).
  5. 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 with stp-failures.py add.
  6. Until the PR merges the row stays backport; after it merges, Step 1 shows same. Do not --keep-game a 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: --adopt records 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 when diff --all shows the template files same.
  • 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 (prints no baseline when 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.

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.json or template-sync.json by hand, never git stash, never --no-fetch to dodge exit 4.
  • Never edit .claude files owned by the T1K kit (everything under .claude/skills/ and .claude/modules/ comes from t1k modules update, never from the template; only sgame-setup/ and sgame-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).