Lessons from moving the Go SDK out of core (preliminary migration playbook)

[rhuss]

The Go SDK move is complete. ai-openshell/sdk-go carries the history and builds on its own, core and SDK v0.1.8 shipped as the first lockstep release on 2026-11-10 (the SDK tag 28 minutes after core's), and #5461 removed sdk/go from core on 2026-11-11. It was the first of the RFC 0019 moves (#4426), so here is what we learned, as a checklist that the next moves (the Python SDK is already under way, then the TypeScript SDK, packages, and windows) can copy.

This replaces the preliminary version from 2026-11-04. Phases 3 to 5 (automation, retirement, first lockstep release) are no longer pending, each phase ends with how it went, and the lessons from release day are in. RFC 0019 hasn't merged yet, so the playbook stays here for now; once it does, I'll propose it as rfc/0019-repository-migration/playbook.md.

Feedback I'd find most useful:

• If you're planning one of the next moves: what's missing for your component?
• If you maintain core CI or the ai-openshell org: is anything here wrong, or would you do it differently?

Next is a migrate-repo agent skill that walks these phases as gated stages, with the history, verification, and porting scripts bundled. The move itself was driven with intent-driven development (cc-spex and spec-kit), and the playbook is meant to be fed to your agents as much as read.

Tracking issue for the Go move: #5031.

Who this is for

Maintainers planning one of the remaining RFC 0019 moves: the Python and TypeScript SDKs, packages, windows, and later the provider repositories. Every move leaves the same core repository, so the lessons about core's PR gates apply to all of them. Placeholders: <component> (for example "Python SDK"), <subdir> (its path in core), <target> (the new ai-openshell/... repository), <surface> (the name core's prompts and scripts use for the component, for example go-sdk).

Phases

Each phase lists its entry gate and a checklist you can copy into the tracking issue. The Go move took six calendar days from the first issue to the core cutover and thirteen to the removal from core, most of it waiting for approvals and for the next core release.

Phase	Gate	Outcome
0 Prerequisites	none	go-ahead, team, settings, drained PRs, freeze commit
1 Import	phase 0	history and a standalone build on <target> main
2 Cutover	phase 1, state:accepted on the core issue	core stops gating on <subdir>, open PRs ported
3 Automation	phase 1, bot App	bump proposals, E2E against releases, release tagging, drift check
4 Retirement	phase 3, final deprecated release from core	<subdir> removed from core
5 Release	phase 3, next core stable release	first lockstep release from <target>

Phase 0: Prerequisites

• File the tracking issue in core. READ contributors can't set labels; ask a maintainer for state:accepted before any core PR.
• Read the target org's rulesets (main-integrity: PR, approval, code owner, last-push approval, no force push) and your access to <target> and ai-openshell/infra (gh api repos/<org>/<repo> --jq .permissions).
• Check live team membership and repository collaborators. The owning team needs at least two members besides the person who pushes, or nothing merges without an admin.
• Write the admin request issue with the exact settings (team permissions, Pages, merge methods including merge commits, who reviews). Keep the bot App out of it; ask for the App in its own issue when phase 3 starts.
• Inventory every reference to the component in core: workflows, tasks/*.toml aggregates, CodeQL matrix and config, release workflows, Dependabot, CODEOWNERS, review prompts and their validators. Search for the path and for <surface>.
• Search the subdirectory's tests for relative paths that climb out of it and list the shared fixtures to vendor.
• Scan open core PRs by file list (not title) for changes under <subdir>. Sort them into component-only PRs, core features with hand-written component changes, and PRs that only regenerate bindings.
• Announce the freeze at least a week ahead on the tracking issue and on each affected PR. Pick a release boundary and say which side late merges land on. Ping a second time a few days before, naming who can unblock what.
• Track each drain PR on four gates: issue acceptance, the CI mirror (/ok to test <sha>), maintainer approval, and open review threads.
• Rehearse extraction, merge, and standalone build on the current tip before the freeze day.

Phase 1: Import

• Record the freeze commit and the pinned core version in the new repository (for example hack/migration/FREEZE).
• Extract with git filter-repo from a throwaway clone reduced to one branch at the freeze commit. Rewrite #N to NVIDIA/OpenShell#N. Run with GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null.
• Verify tree hash, commit, author, and sign-off counts, and grep for bare references. Put the output in the import PR.
• Merge the history into <target> with --allow-unrelated-histories and a merge commit. Resolve the auto-init README conflict in favor of the component's README.
• Make the component standalone in a second PR: new package or module path, bindings generated from a pinned core release, self-contained task runner, vendored fixtures plus a check against the pinned source, LICENSE, CI.
• Rerun the climbing-path search on the freeze tree; PRs merged in the last days can add new shared fixtures.
• Grep docs config and README for old repository URLs and personal mirrors.
• Smoke-test as a consumer from a clean environment (install from main, build the README example).

Phase 2: Cutover and porting

• Open one core issue per core PR (the tracking issue stays open, so it can't be the closing issue) and get each accepted.
• Core PR A: deprecation notice, moved-notice README, drop the CI gate that forced changes under <subdir>, and add a required check that fails on added or modified files there. Exempt deletions and the notice files instead of relying on a label.
• Ask for exactly one area label that has a reviewer table in REVIEWERS.md, together with /ok to test. After the CI mirror runs, answer review comments without pushing and carry polish into the next PR.
• Port open PRs with format-patch --relative=<subdir> --no-signoff and git am. Rewrite renamed paths inside the patches before applying, and only in lines the port adds. Port only the top PR of a stack.
• Comment on each ported core PR with its replacement and ask the author to close it.
• After a squash merge in <target>, rebase every stacked branch right away. Verify each push with git ls-remote and read lease SHAs from it.
• Prove the approval path: a code owner other than the last pusher approves and merges a PR without an admin.

Phase 3: Automation

• Governance PR: CODEOWNERS (check team slugs with gh api orgs/<org>/teams; every team named needs repository access), Dependabot, CodeQL, workflow linting (actionlint, zizmor, shellcheck), docs publishing, CONTRIBUTING, SECURITY, AGENTS. Follow org-wide choices (the DCO GitHub app) over copies from core.
• Make the new repository's CI and workflow checks required on main before the first automated PR arrives. Required DCO alone let a failing dependency update merge.
• Run zizmor on every workflow copied from core before adopting it.
• Request the bot App with the minimum permissions the workflows use (contents, pull requests, issues, metadata). Store its client ID and private key in an environment that only main can deploy to.
• Poll core releases on a schedule instead of cross-org push triggers. Propose only the newest pre-release of a train, and close the proposal it supersedes.
• Base the E2E lane on core's supported container deployment at the released tag, not on core's from-source test setup.
• Dry-run bump proposals, release tagging, and the drift check against a real version pair before going live.
• After the automation merges: dispatch the release tagging once for the version the standalone PR pinned, dispatch the watcher once, and run both again to see that nothing duplicates.
• Give the release notes their own template: the changes since the previous release of <target> and anything consumers must do.

How it went: the first live watcher run opened a bot PR with CI and E2E on it. Over 140 hourly runs proposed every pre-release once, with no duplicates. The nightly drift check stayed quiet against core main and keeps a single issue. Bot steps that need PR context (an agent triggered by a label) can't reach secrets limited to main, so they need their own design (pull_request_target restricted to the bot's branches is one option).

Phase 4: Retirement

• Wait for a core stable release that contains PR A. Let that release create the final tag of the old path through its regular workflow; a manual tag at another commit makes the release's tag job fail. Keep the tagging workflow until then.
• Core PR B: remove <subdir>, its tasks and toolchain, CodeQL entries, release jobs and their needs and expected-job checks, and the freeze check. Rewrite the user docs page for the new location, with examples compiled against the new package.
• Rebase PR B right before opening it. Other moves change the same CI and release files in parallel (the Python SDK move caused all four conflicts in the Go PR B).
• Run the sync-agent-infra skill and search for <surface> as well as the path. Check that the removed jobs are not required status contexts.
• Verify the old path: the package index shows the deprecation, and existing versions still install.
• Close the tracking issue with a summary against its acceptance criteria.

How it went: the Go module proxy and pkg.go.dev showed the deprecation as soon as the release created sdk/go/v0.1.8, and go get prints it. Core's docs page now describes the new package and keeps the migration steps from the old one.

Phase 5: Release

• Before core's release day, check that <target>'s main is green: the stable proposal opens minutes after the core release and inherits whatever is red.
• Have a second reviewer available. A maintainer who pushes a fix onto the bot's proposal becomes its last pusher and can't approve it.
• Merge the stable proposal; the automation tags the release with notes that name the core version. Review the notes against the template.
• Link the releases page from the README; with lockstep versions, a separate table of supported versions only repeats it.
• Run every quickstart check end to end and close the migration log.

How it went: core v0.1.8 was released at 18:14 UTC, and SDK v0.1.8 was tagged at 18:42 UTC. Two fixes landed in between: the Go toolchain, after a dependency update had raised the minimum, and a README version line that the stable proposal hadn't updated after a merged pre-release proposal.

Lessons by topic

Governance

• Check the target org's rulesets before assuming push access. ai-openshell applies main-integrity to every Terraform-managed repo, and only org admins can bypass.
• require_last_push_approval plus a team without a second reviewer means nothing can merge without an admin. Grow the owning team before the move.
• Prove the approval path on a real PR before the cutover.
• Ask for the smallest repository role that works. Write covers labels, workflows, tags, releases, and Pages deploys. Only Actions secrets and security settings need repository admin, and an org admin can set those once. Repository admin doesn't bypass org rulesets.
• Spell out the target settings in the request issue instead of "an infra PR follows". In the Go move the admin applied them directly from the issue text.
• Being able to clone a private infra repo doesn't mean you can push to it, and org repos may disable forking.
• Check live team membership and the repository's collaborators before drafting governance requests. Terraform history can hold changes the plan missed.
• Check team slugs before writing CODEOWNERS; display names can differ from slugs (maintainers, not openshell-maintainers).
• A CODEOWNERS rule only works for a team with access to the repository. When reviewers ask for a path owned by another team, request that team's access in the same comment.
• Follow the org's existing choices over copies from core. The org installs the DCO GitHub app on every public repo, so the new repo needs neither a DCO workflow nor a DCO file.
• Repo settings, teams, and members live in ai-openshell/infra. Plan an infra change (made by an infra team member) as step zero.
• Contributors with READ on NVIDIA/OpenShell need a state:accepted issue for every core-side PR. The tracking issue must stay open, so file one issue per core PR.
• Make the new repository's CI a required check before the first automated PR arrives.

Automation identity

• PRs opened with GITHUB_TOKEN do not trigger workflows. Bot PRs need a GitHub App token.
• Ask for the bot App only when the automation phase starts, in its own issue.
• Request the App with the minimum permissions the workflows use, and check whether any workflow edits workflow files before asking for workflows: write.
• Keep bot App secrets in an environment that only the default branch can deploy to. Repository secrets let any pushed branch mint a bot token, push as the bot, and approve its own change.
• An environment limited to the default branch rules out bot steps in PR context. Design those as separate workflows from the start.
• Polling core on a schedule avoids cross-org secrets. Use push triggers only once a cross-org App exists.
• A shell GITHUB_TOKEN overrides the gh keyring login. Check gh auth status when a push of workflow files fails with a missing workflow scope.
• Last-push approval applies to bot PRs too: a human fix pushed onto a bot PR needs another approver.
• A failure step inside a workflow can't report a run that fails before any job starts. Check the run list now and then, not only the failure log the automation keeps.

CI coupling

• Inventory every place core CI references the component before planning the removal.
• Search for the component's surface name as well as its paths. Review prompts and their validators can name a component without referring to its directory.
• Search the subtree's tests for relative paths that climb out of it. Shared fixtures in core break silently on extraction; vendor them and add a check against the pinned source.
• Rerun that search on the freeze tree after the rehearsal. A fixture newer than the pinned tag can't be checked against it yet.
• Run zizmor on workflows copied from core before adopting them. Suppressions in core's config hide findings a new repo doesn't need to inherit.
• Read core's E2E setup before planning the new repo's lane, and base the lane on core's supported container deployment (compose file, Helm chart) when it runs published images.

Releases

• Directory-prefixed tags (sdk/go/vX.Y.Z) can break tooling that runs git describe (setuptools-scm in fix(ci): keep Release Dev publishing when the snap upload or a Go tag breaks it #5018). Separate repos remove that class of problem.
• Dry-run release automation against a real version pair before going live. The compare API silently truncates at 300 files, and gh api puts 404 error JSON on stdout.
• Fix the freeze to a release boundary and say which side late merges land on. In the Go move, freezing at the end of the release day put three fixes into the new repo that core's tag of the same version lacks.
• Pre-release proposals leave state behind. When a pre-release pin is merged, anything a stable proposal rewrites must not assume the previous pin was stable.
• Generated release notes need their own template. Reusing the update PR's body shipped a reviewer checklist and missed a new toolchain minimum.
• Check the new repo's main before core's release day; the stable proposal inherits whatever is red.
• A package version can be permanent once published (the Go module proxy keeps it). Dry-run the first release tag before dispatching it.
• Language ecosystems move their minimum toolchain with their support window (the golang.org/x modules follow the two supported Go releases). The toolchain pin, and the consumers' minimum, move with them.

History

• Most commits touching a subdirectory may be cross-cutting core work (66 of 79 for sdk/go). Filtered history keeps them, which is acceptable in exchange for blame and authorship.
• Rewrite #N references to NVIDIA/OpenShell#N during extraction, or they autolink to the new repo's issues.
• If the target repo was auto-initialized, the import needs a merge commit, so that merge method must be allowed, and README.md conflicts. Rehearse the merge along with the extraction.
• git filter-repo crashes on multi-line alias values in git config --list. Run it with GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null.
• Reduce the extraction clone to one branch at the freeze commit before filtering.
• A verification script (tree hash, commit, author, and sign-off counts, bare references) makes the import PR reviewable from any core checkout. The whole extraction takes seconds, so rehearse it.

Deprecation

• Retire in two core PRs: deprecate and drop the CI gate first, remove the code after the final deprecated release and once the new repo's automation is live.
• A freeze announced only by comment doesn't stop merges. Add a required check that fails on changes to the moved directory, together with dropping the gate that forced those changes.
• Let that check exempt deletions and the notice files instead of relying on an exception label; READ contributors can't create or set labels.
• Let core's regular release create the final tag of the old path. Keep its tagging workflow until then and remove it together with the code.
• Other moves run in parallel and touch the same CI and release files. Rebase the removal PR right before opening it.

Porting

• Drain scans need the PR file lists, not titles. Most PRs that touch the component are core features that update bindings or wrappers alongside.
• Announce the freeze at least a week ahead and ping twice. Acceptance labels and reviews arrived only after the second, more specific ping.
• Track each drain PR on four gates: issue acceptance, CI mirror, maintainer approval, open review threads. A green check on one says nothing about the others.
• "PR Issue Acceptance" needs a closing keyword; "Part of #N" fails even when the issue is accepted.
• /ok to test is pinned to a SHA. Every push by the author needs a new one, so a PR fixed after review silently waits again.
• Review Readiness needs exactly one area label with a reviewer table in REVIEWERS.md; an existing GitHub label is not enough.
• Fork PRs hold pull_request workflows as "awaiting approval" until a maintainer clicks "Approve and run". They are not part of Required CI Gates.
• After an /ok to test lands, don't push non-blocking polish. Answer the review and carry the polish into the next PR.
• Authors often push fixes with a top-level summary instead of thread replies. A review pass on freeze day that maps each thread to fixed or deferred saves approvers from reconstructing it.
• Port with format-patch --relative=<subdir> plus git am, and rewrite renamed paths inside the patches before applying.
• Pass --no-signoff to format-patch; a porter's format.signoff=true adds their sign-off to every contributor's commit.
• Never rewrite old paths across the whole tree after a port. The new repo mentions them on purpose in migration notes.
• A 3-way am resolution with --theirs still has old paths. Rewrite the resolved lines before git am --continue.
• Check for stacked PRs and port only the top one.
• A squash merge of a stacked PR leaves its original commits on every branch above it. Rebase the stack right after the merge.
• Verify pushes with git ls-remote, not the push output, and read lease SHAs from it too.

Docs

• Grep docs config and README for the old repository and for personal mirrors. They survive the path rewrite because they don't contain the path.
• Compile and vet the user docs' examples against the new package before the removal PR, and keep the migration steps on core's docs page for a release.
• Carry docs notes from ported PRs into the new repo's guides as their own commit.

[rhuss]

Update after the first lockstep release (core and SDK v0.1.8)

The automation phase is done, and the retirement PR is open (#5461). What we learned since the first post:

• [generic] Required checks from the first day. sdk-go's ruleset required only DCO. A Dependabot update that needed a newer Go toolchain merged with ci failing (chore(deps): bump the go-minor-and-patch group with 5 updates ai-openshell/sdk-go#14), and main stayed red until build: move the Go toolchain to 1.26 ai-openshell/sdk-go#32, the afternoon of the release. Make the new repository's CI a required check before the first automated PR arrives.
• [generic] The final deprecated tag comes from the regular release. Core's v0.1.8 release created sdk/go/v0.1.8 from a commit that already carried the deprecation. A manual tag before the release would have failed it, because the tagging job refuses an existing tag at another commit. Remove the tagging workflow with the code, not before.
• [generic] Pre-release proposals leave state behind. sdk-go merged a pre-release proposal (v0.1.8-pre.3), so the stable proposal's README update looked for the wrong old version and changed nothing. Anything a stable proposal rewrites must not assume the previous pin was stable (fixed in fix(hack): update the README version line after pre-release pins ai-openshell/sdk-go#34).
• [generic] Last-push approval meets bot PRs. When a maintainer pushes a fix onto the bot's update PR, they become the last pusher and need another approver, so plan for a second reviewer on release day.
• [generic] Generated release notes need their own template. Reusing the update PR's body put a reviewer checklist into the v0.1.8 release notes and left out the Go 1.26 requirement. The notes should list the changes since the previous SDK release.
• [go] Track the language's support window. The golang.org/x modules follow the two supported Go releases, so the toolchain pin has to move with them, and the SDK's minimum Go version moved to 1.26.

Timeline on release day: core v0.1.8 at 18:14 UTC, SDK v0.1.8 tagged at 18:42 UTC, with two fixes (Go toolchain, README line) merged in between.

[rhuss]

I updated the post above to the final playbook: phases 3 to 5 are filled in from the run, each phase ends with how it went, and the release-day lessons from my previous comment are part of it.