execute-v2-migration

Use this skill when user requests to execute or implement a Crossplane v2 migration plan. Executes the migration plan generated by plan-v2-migration stage by stage, updating each function's tests to v

SKILL.md

GitHub

Crossplane v2 migration executor

Carry out the plan plan-v2-migration wrote to .agents/plans/CROSSPLANE_V2_MIGRATION.md, stage by stage, ticking each item as it is done.

Before you start

Load control-plane-project-charter first, or read its SKILL.md beside this skill's directory; this skill does not load it. Ask only at the points this skill names, and only when interactive; unattended, take the default named at each point and state it in the summary (charter §1). Its §4 binds every summary.

  • No plan, no migration: without .agents/plans/CROSSPLANE_V2_MIGRATION.md, stop and point to plan-v2-migration.
  • What each change means is in plan-v2-migration breaking-changes.md, whose sections the plan points at. Read the section before you edit. Upstream: the Crossplane v2 upgrade guide.
  • You edit YAML directly (stages 1–4, 6, 8). Tests and functions go to author-tests and author-composition, verification to verify-configuration and e2e-test-configuration, each as a sub-agent with a brief from phases.md. Wait for each report. With no sub-agents, follow the brief yourself (control-plane-project-charter §1).
  • Never delete a branch or anything on a control plane, and never rename a function to add a language suffix: its name is the published package name.

Arguments

Argument Runs
none, or all stages 1–8 in order
2 3 4 those stages; earlier unticked stages are reported, not run
continue from the first unticked item in the plan

Stage 0: Pre-flight

Check the worktree state and whether migrate-to-v2 exists locally or on the remote first. If it does, switch to it (check it out if it is local, track it if it is only on the remote) before anything else: the plan and its ticks may exist only there. Then check that the plan exists and the project is still v1 where the plan says so (commands: phases.md). Take the languages from the plan, or detect them with control-plane-project-charter/references/languages/README.md, and read the language file.

Point Interactive Unattended
Go-ahead show the scope; ask once "Execute the migration?" the request that started you is the go-ahead
Uncommitted changes ask: commit first, or continue continue only if no file the plan touches is dirty; else stop and report
migrate-to-v2 exists, locally or on the remote ask: continue on it continue on it with continue semantics, and say so

If the branch did not exist, create it after the go-ahead, whichever stages were asked for, and before the first one runs. Tick the plan's branch item. It happens here, not in stage 1, because a run of 2 3 4 skips stage 1 and would otherwise edit main.

Stage 1: Prepare

On migrate-to-v2, which stage 0 checked out: upbound.yaml (apiVersion, dependency versions, apiDependencies), then up dep update-cache and up project build. Checkpoint: the build succeeds and the models contain the .m. groups. Otherwise stop and report.

Stages 2–4: XRDs, compositions, examples

Edit each file with the plan's items. Checkpoint: yq '.' <file> parses, per file. Otherwise stop and report the file.

Stage 5: Tests, then functions

Tests lead. A migration starts from working code, so there is no natural RED. For each function, update its tests to v2 and watch them fail against the unmigrated function — for the v2 reason, not a compile error — then migrate the function until they pass: the loop in control-plane-project-charter §3. A plan item no updated test turned red is proven by mutation (control-plane-project-charter/references/charter/tdd.md) or reported as uncovered. Procedure and briefs: phases.md.

Checkpoints: after the tests, up test run "tests/<test>" fails on a v2 difference; after the function, the language's compile check (KCL kcl lint, Python ast parse, Go go vet), then up test run "tests/test-*" passes. A failed sub-agent gets one retry with the failure in its brief (interactive: offer it), then stop and report.

Stage 6: Renames

Only the renames the plan lists, which follow a deliberate Kind rename; git mv, then functionRef.name and step. Checkpoint: up project build succeeds. Otherwise stop and report.

Stage 7: Verification

The build and every composition test through verify-configuration; then render one example and read it. Checkpoint: all composition tests pass. If not, stop: no E2E, report the failures, resume with continue after the fix.

E2E tests create cloud resources. Interactive: ask once whether to run them and on which target (local kind or a Space group). Unattended: do not run them unless the request that started you said to and named the target; otherwise report them as not run.

Stage 8: Documentation

Update what the plan lists (README, CI). Interactive: ask before rewriting README prose beyond the mechanical changes. Unattended: make the mechanical changes and list the rest.

Success criteria

Checks for you before you report, not a report format (control-plane-project-charter §4).

  • Every plan item is ticked, or listed as not done with the reason.
  • For each function, its updated tests were seen failing before the migration and passing after, or the summary says which were not and why.
  • Build and composition-test results are quoted from the runs' own output; E2E results, or "not run" with the reason.
  • The summary follows the final summary template.