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.mdskills/execute-v2-migration/SKILL.md
GitHubCrossplane 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 toplan-v2-migration. - What each change means is in
plan-v2-migrationbreaking-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-testsandauthor-composition, verification toverify-configurationande2e-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.