t1k:unity:base:gdk-migrate
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | high |
| Tools | Bash, Edit, Glob, Grep, Read, Write |
Keywords: ai/gdk-migrate, gdk migration branch collision, GDK origin master, migrate GDK, push migration branch, submodule compile errors, UITemplate migration, update GDK, update submodules
How to invoke
Section titled “How to invoke”/t1k:unity:base:gdk-migrate[plan|apply|verify|resume]T1K Unity GDK and submodule migration
Section titled “T1K Unity GDK and submodule migration”Upgrade all direct submodules, migrate the Unity consumer project across GDK breaking changes, and validate with a real Unity compilation. Continue autonomously through ordinary in-scope edits; stop only at a named ambiguity or safety boundary.
Invocation modes
Section titled “Invocation modes”plan: inspect, resolve immutable targets, and write the lock/report without changing gitlinks.applyor no argument: execute the complete update, repair, validation, and publish workflow.verify: make no source or gitlink edits; validate the existing lock and migration result.resume: continue from the existing lock/report without resolving targets again.
plan and verify never create a branch, commit, or push. Only apply and
resume publish, and only after the full validation matrix passes.
Required context
Section titled “Required context”Read references/migration-workflow.md before acting. Also read
references/theone-5-consumer-migration.md when the diff or diagnostics touch
TheOne 5, UITemplate, GDK UI, popup, tab, virtualized-list, or scene-loading APIs.
Treat those references as guidance, then verify every claim against the frozen
old/new revisions in the current project.
Step 0 — Pre-flight (run before anything else)
Section titled “Step 0 — Pre-flight (run before anything else)”Three bundled scripts make a single invocation self-sufficient.
Resolve <skill-dir> from the directory of the SKILL.md you just read; never find (it matches stale .claude/.t1k-preserved/ backups). Candidate order and the derivation snippet: references/preflight-details.md.
for d in "$PWD/.claude/skills/t1k-unity-base-gdk-migrate" \ "$HOME/.claude/skills/t1k-unity-base-gdk-migrate"; do [ -f "$d/SKILL.md" ] && SKILL_DIR="$d" && breakdoneREPO=/absolute/path/to/the/superprojectBefore running the pre-gate, resolve a read-only migration baseline with the bundled selector:
BASELINE_INFO=$(bash "$SKILL_DIR/scripts/gdk-select-baseline.sh" "$REPO")BASELINE_SHA=$(printf '%s\n' "$BASELINE_INFO" | sed -n 's/^baselineSha=//p')printf '%s\n' "$BASELINE_INFO"Selection rules (integration ref, origin/ai/gdk-migrate ancestry, git cherry patch equivalence): references/preflight-details.md.
Record the selected ref, SHA, and reason as baselineRef, baselineSha, and
baselineReason in the lock/report. Selection is read-only in plan and
verify; do not create or move a local branch in those modes.
-
Pre-gate — is there anything to do?
Terminal window bash "$SKILL_DIR/scripts/gdk-pregate.sh" "$REPO" "$BASELINE_SHA"# exit 0 = a GDK pin moved · 10 = nothing moved · 11 = pin(s) ahead of master# · 2 = not a GDK consumerPins compare by ancestry, not string equality: a strict descendant of
origin/masteris a deliberate unmerged fix. Details:references/preflight-details.md.Exit
10: report “GDK already current, nothing to migrate” and STOP — do not resolve targets, do not write a lock. Exit2: this project consumes no GDK submodule; report that and STOP.Exit
11: recordBLOCKED: GDK pin ahead of origin/master (unmerged upstream fix)and STOP; only exit0continues. A squash-merged upstream leaves this permanent: repin manually once the work lands (references/preflight-details.md). -
Generate the freeze policy.
Terminal window bash "$SKILL_DIR/scripts/gdk-gen-policy.sh" "$REPO"Writes
<repo>/gdk-migration-policy.json. Regenerate it every run; never commit it and never hand-edit it.Each non-GDK direct submodule is FREEZE (listed; the default) or ALLOW (omitted; fast-forwards to
masteronly when it hasorigin/masterand its pin is a strict ancestor). The generator reads recorded gitlinks (git ls-tree), never a worktreeHEAD. Why branch-per-game forks are frozen:references/preflight-details.md.
Both scripts discover the submodule set from .gitmodules and match GDK repos by
path suffix, so they are identical for every project and need no per-project
configuration. Note Assets/UITemplate is a GDK repo while UITemplateComponent
is not — the suffix match distinguishes them; a prefix match would not.
Workflow
Section titled “Workflow”- Snapshot the superproject, every direct submodule, tracked
.metafiles, and existing user changes. Prefer an isolated worktree based on the selected migration baseline and never discard unrelated changes. - Discover submodules from Git configuration. Fetch each remote, record old
SHAs, resolve targets using the rules below, and freeze them in
gdk-migration-lock.json. - Inspect
oldSha..targetShabefore editing. Map asmdef/asmref, GUID, namespace, public API, package, define, and serialized-type changes to all consumers. - Write the planned changes to
gdk-migration-report.md, checkout frozen target SHAs, and migrate consumers with the smallest semantic change. - Run Unity batch-mode compilation, parse the log for actual package-resolution and compiler evidence, repair attributable errors, and repeat to zero errors.
- Validate gitlinks, clean submodules, GUID uniqueness, asmdef resolution, missing-script evidence, and relevant tests. Finish the report with exact results and reproduction commands.
- Publish only once that matrix passes in full (see Publish). Each submodule gets its own per-lineage branch
ai/gdk-migrate-<pin8>(pin8= first 8 hex of its frozenoldSha), never a shared bareai/gdk-migrate. - Query the live remote,
git ls-remote --heads origin ai/gdk-migrate, before choosing the push strategy; never trust the preflight’s local ref. Details:references/publish-details.md.
Target resolution
Section titled “Target resolution”-
com.gdk.core,com.gdk.3rd, andAssets/UITemplatemust resolve to the fetchedrefs/remotes/origin/mastercommit. -
For every other direct submodule, an explicit
gdk-migration-policy.jsonrefis authoritative. Step 0 generates that file; its shape is:Policy shape: a
submodulesmap of<.gitmodules path>to{"ref": "<40-char SHA>"}, plussubmoduleSourceEditsandallowNonFastForward. Full example:references/preflight-details.md.A path present in
submodulesis FROZEN at itsref— never move that gitlink, even if a newer descendant tip exists. A path absent from the file is deliberately allowed to advance: fall through to the descendant rule below. Absence is a decision the generator made, not an oversight. Keys prefixed_are commentary; ignore them. -
Without policy, choose the unique newest fetched remote tip that descends from the current pin. A tip with no newer descendant is a valid no-op.
-
Never equate
origin/HEADwith latest. Multiple incomparable descendants or a non-descendant target withoutallowNonFastForward: trueare BLOCKED. -
Freeze full SHAs once per run; never re-resolve midway.
Non-GDK submodule repairs
Section titled “Non-GDK submodule repairs”Scan non-GDK submodules for removed-GDK-API use even when their target is unchanged. A repair goes on the durable ai/gdk-migrate branch as a local commit, stays local until publish, and is never an empty commit. BLOCKED if that branch cannot advance without force-push or holds unexplained work. Details: references/publish-details.md.
Publish
Section titled “Publish”Publishing is gated on the full success condition, never on the compile alone. On BLOCKED or FAILED, push nothing. A local submodule repair branch may already exist from the repair phase; report it explicitly and leave it unpushed.
-
Push repaired submodules FIRST. For each submodule carrying a
resultSha, push its durableai/gdk-migratebranch to that submodule’s ownoriginand confirm the remote ref now containsresultSha. A superproject gitlink pointing at an unpushed commit is not clone-reproducible. Never delete, recreate, or force-update this branch. -
Use
ai/gdk-migrateas the superproject’s reusable PR branch and honor the frozenbaselineRef(continue fromorigin/ai/gdk-migratewhen it was the baseline; otherwise rebuild from the integration ref). Details:references/publish-details.md. The user creates or updates the PR from it but never commits or pushes to it. -
Commit by explicit pathspec — changed gitlinks, consumer sources, manifests, asmdefs, the lock, and the report. Never
git add -A,git commit -a, or--amend. Readgit diff --cachedfirst and drop anything this migration did not produce. -
Push
ai/gdk-migratewith--set-upstreamwhen the remote branch is absent. When continuing fromorigin/ai/gdk-migrate, push normally; this must be a fast-forward of the observed remote SHA. When rebuilding from the integration ref after an earlier migration was integrated, replace the old remote tip using an explicit lease tied to the SHA recorded after fetch:Terminal window git push --set-upstream origin \--force-with-lease=refs/heads/ai/gdk-migrate:<observed-remote-sha> \ai/gdk-migrate:refs/heads/ai/gdk-migrateNever use plain
--force, never retry a rejected lease by refreshing it, and never push tomain,master,develop, orstaging. A lease rejection means someone or something changed the supposedly Claude-owned branch; stop and report BLOCKED. -
Report the branch name, pushed superproject SHA, every submodule branch and
resultShapushed, and the compare URL fromai/gdk-migrateto the selected integration branch. Opening the PR is out of scope: the user owns creating or updating that PR and must not edit or push directly toai/gdk-migrate.
Record the same facts in gdk-migration-report.md. A branch that exists locally
but was never pushed is not published; say so explicitly.
Success and stop conditions
Section titled “Success and stop conditions”SUCCESS requires zero Unity compile errors, clean submodule worktrees, all
resolved remote updates applied, every locally repaired submodule pinned to its
recorded resultSha, and — in apply and resume — the migration branch
pushed with every submodule resultSha reachable on its own remote. Source
inspection alone is not success, and an unpushed local branch is not a completed
publish.
Report BLOCKED when a target is ambiguous, a forbidden non-fast-forward is required, a duplicate GUID has ambiguous ownership, the frozen GDK dependency set itself fails, a required local submodule repair cannot be committed, a serialized type lacks a safe migration, materially different replacements exist, the same root cause survives two repair attempts, the reusable migration branch changed after its lease was recorded, or a required push is rejected for permission or lease reasons.
Executed by
Section titled “Executed by”The pre-flight/baseline scripts (scripts/gdk-*.sh) are mechanical: t1k-fact-fetcher may run them. The migration, compile loop and publish stay reasoning-tier (t1k-unity-base-developer).
Hard rules
Section titled “Hard rules”- Unity exit code zero does not prove scripts compiled; require log evidence that package resolution and compilation completed, then search actual diagnostics.
- An open interactive Editor blocks batch mode outright. If anyone has the
project open,
-batchmodeaborts immediately with “It looks like another Unity instance is running with this project open” — before package resolution or any compilation. Report BLOCKED and ask for the Editor to be closed; never kill, quit or restart it yourself. A different project’s Editor does not conflict. CI never hits this (fresh clone, no Editor); developer machines hit it constantly. -runTestsand-quittogether silently run nothing. Unity’s test runner ends the process itself, so passing-quitas well makes the editor exit before a single test executes — and it looks like a clean pass. Omit-quitwhenever running tests.- Vendor SDKs mutate the project on Editor load. Observed: AppLovin MAX’s
AppLovinInitializeself-updatescom.applovin.mediation.adsand, viaRemoveObsoleteNetworkPackages, strips mediation adapters out ofmanifest.jsonon every Editor session. Diffmanifest.jsonbefore committing and revert anything the migration did not intend — silently dropping a monetization network is a product decision this workflow must never make. - Unity may mutate generated files and
.metastate. Snapshot first and exclude unrelated Editor side effects from the migration diff. - Do not delete references, calls, features, or files merely to suppress errors.
- Do not patch GDK source locally; repair its consumers or report an upstream defect.
- Preserve GUIDs and serialized continuity whenever upstream supplies a supported replacement.
- Never answer a rejected push with plain
--force, a refreshed lease, a rebase onto an unrelated branch, or a retargeted protected branch. The only permitted history replacement is the explicit, previously recorded--force-with-leasefor the Claude-owned superprojectai/gdk-migratebranch. Report BLOCKED when that lease is rejected.