Execute V2 Migration

---
name: execute-v2-migration
description: 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 v2 before migrating the function. Use immediately when user says "execute the migration", "implement the v2 migration", "run the migration plan", or "migrate to v2 now". Use this skill instead of manually executing migration steps. This skill reads .agents/plans/CROSSPLANE_V2_MIGRATION.md and executes it, editing YAML directly and handing functions, tests and verification to author-composition, author-tests, verify-configuration and e2e-test-configuration.
license: Apache-2.0
references:
  - references/phases.md
---

# 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](https://docs.crossplane.io/latest/guides/upgrade-to-crossplane-v2/).
- 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](references/phases.md#sub-agent-briefs).
  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 that the plan exists, the project is still v1 where the plan says so, the worktree state, and
whether `migrate-to-v2` exists (commands: [phases.md](references/phases.md#stage-0-pre-flight)).
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 | ask: continue on it | continue on it with `continue` semantics, and say so |

## Stage 1: Prepare

Branch (work on `migrate-to-v2`), `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.

## 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](references/phases.md#stage-5-tests-then-functions).

**Checkpoints:** after the tests, `up test run "tests/<test>"` fails on a v2 difference; after
the function, the language's compile check (KCL `kcl`, 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`.

## 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](references/phases.md#final-summary-template).