Skip to content

t1k:unity:base:gdk-migrate

FieldValue
Modulebase
Version5.116.6
Efforthigh
ToolsBash, 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

/t1k:unity:base:gdk-migrate
[plan|apply|verify|resume]

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.

  • plan: inspect, resolve immutable targets, and write the lock/report without changing gitlinks.
  • apply or 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.

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.

Terminal window
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" && break
done
REPO=/absolute/path/to/the/superproject

Before running the pre-gate, resolve a read-only migration baseline with the bundled selector:

Terminal window
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.

  1. 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 consumer

    Pins compare by ancestry, not string equality: a strict descendant of origin/master is 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. Exit 2: this project consumes no GDK submodule; report that and STOP.

    Exit 11: record BLOCKED: GDK pin ahead of origin/master (unmerged upstream fix) and STOP; only exit 0 continues. A squash-merged upstream leaves this permanent: repin manually once the work lands (references/preflight-details.md).

  2. 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 master only when it has origin/master and its pin is a strict ancestor). The generator reads recorded gitlinks (git ls-tree), never a worktree HEAD. 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.

  1. Snapshot the superproject, every direct submodule, tracked .meta files, and existing user changes. Prefer an isolated worktree based on the selected migration baseline and never discard unrelated changes.
  2. 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.
  3. Inspect oldSha..targetSha before editing. Map asmdef/asmref, GUID, namespace, public API, package, define, and serialized-type changes to all consumers.
  4. Write the planned changes to gdk-migration-report.md, checkout frozen target SHAs, and migrate consumers with the smallest semantic change.
  5. Run Unity batch-mode compilation, parse the log for actual package-resolution and compiler evidence, repair attributable errors, and repeat to zero errors.
  6. Validate gitlinks, clean submodules, GUID uniqueness, asmdef resolution, missing-script evidence, and relevant tests. Finish the report with exact results and reproduction commands.
  7. 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 frozen oldSha), never a shared bare ai/gdk-migrate.
  8. 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.
  • com.gdk.core, com.gdk.3rd, and Assets/UITemplate must resolve to the fetched refs/remotes/origin/master commit.

  • For every other direct submodule, an explicit gdk-migration-policy.json ref is authoritative. Step 0 generates that file; its shape is:

    Policy shape: a submodules map of <.gitmodules path> to {"ref": "<40-char SHA>"}, plus submoduleSourceEdits and allowNonFastForward. Full example: references/preflight-details.md.

    A path present in submodules is FROZEN at its ref — 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/HEAD with latest. Multiple incomparable descendants or a non-descendant target without allowNonFastForward: true are BLOCKED.

  • Freeze full SHAs once per run; never re-resolve midway.

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.

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.

  1. Push repaired submodules FIRST. For each submodule carrying a resultSha, push its durable ai/gdk-migrate branch to that submodule’s own origin and confirm the remote ref now contains resultSha. A superproject gitlink pointing at an unpushed commit is not clone-reproducible. Never delete, recreate, or force-update this branch.

  2. Use ai/gdk-migrate as the superproject’s reusable PR branch and honor the frozen baselineRef (continue from origin/ai/gdk-migrate when 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.

  3. Commit by explicit pathspec — changed gitlinks, consumer sources, manifests, asmdefs, the lock, and the report. Never git add -A, git commit -a, or --amend. Read git diff --cached first and drop anything this migration did not produce.

  4. Push ai/gdk-migrate with --set-upstream when the remote branch is absent. When continuing from origin/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-migrate

    Never use plain --force, never retry a rejected lease by refreshing it, and never push to main, master, develop, or staging. A lease rejection means someone or something changed the supposedly Claude-owned branch; stop and report BLOCKED.

  5. Report the branch name, pushed superproject SHA, every submodule branch and resultSha pushed, and the compare URL from ai/gdk-migrate to 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 to ai/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 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.

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

  • 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, -batchmode aborts 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.
  • -runTests and -quit together silently run nothing. Unity’s test runner ends the process itself, so passing -quit as well makes the editor exit before a single test executes — and it looks like a clean pass. Omit -quit whenever running tests.
  • Vendor SDKs mutate the project on Editor load. Observed: AppLovin MAX’s AppLovinInitialize self-updates com.applovin.mediation.ads and, via RemoveObsoleteNetworkPackages, strips mediation adapters out of manifest.json on every Editor session. Diff manifest.json before 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 .meta state. 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-lease for the Claude-owned superproject ai/gdk-migrate branch. Report BLOCKED when that lease is rejected.