Add mapi -> capi migration subagent

[theobarberbany]

Experimental subagent that is an expert in the mapi2capi migration.

Generated with the Claude Code /agent command, refined getting gemini to critique Claude's work 🤣 Then edited by hand for accuracy.

Summary by CodeRabbit

• Documentation
  • Added an in-depth guide covering the OpenShift MAPI to CAPI migration architecture. Includes controller roles and responsibilities, handover protocol, resource mappings and conversion flows, feature gating, policy enforcement, finalizer handling, and platform-specific notes. Provides step-by-step migration guidance, troubleshooting playbooks, and communication best practices to support planning, execution, and issue resolution during migration.

[openshift-ci]

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

[coderabbitai]

Walkthrough

Adds a new documentation file (.claude/agents/mapi-capi-migration-expert.md) describing OpenShift MAPI→CAPI migration architecture and protocols, including controller roles, resource mappings, sync and migration flows, gating and policy enforcement, finalizer/handover steps, platform-specific notes, troubleshooting, and communication guidelines.

Changes

Cohort / File(s)	Summary
Documentation: MAPI→CAPI migration expert guide .\claude\agents\mapi-capi-migration-expert.md	New expert-oriented doc detailing MAPI↔CAPI resource mapping, sync vs. migration controller roles, generation-based tracking, paused-condition protocol, finalizer handling, feature gating, VAP/CEL enforcement, conversion notes, handover sequence, troubleshooting, and codebase pointers.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor Operator
  participant FG as FeatureGate
  participant VAP as VAP/CEL Policy
  participant MSC as machine-api-sync-controller
  participant SYNCC as machine-syncc
  participant MAC as machine-api-migration-controller
  participant MAPI as MAPI Resources
  participant CAPI as CAPI Resources

  Operator->>FG: Enable migration feature gate
  FG-->>MAC: Gate opens migration controllers
  MAC->>MAPI: Reconcile, add paused conditions
  MAC->>MSC: Coordinate sync freeze (handover start)
  MSC-->>MAPI: Stop updates where paused
  MAC->>MAPI: Add handover finalizers
  MAC->>MAPI: Convert/spec map to CAPI
  MAC->>CAPI: Create/Update CAPI resources
  VAP-->>MAC: Validate via CEL policies
  MAC->>CAPI: Set ownership/labels
  SYNCC->>CAPI: Steady-state sync (post-creation)
  MAC->>MAPI: Remove finalizers upon completion
  MAC->>MSC: Resume sync (handover end)
  MSC-->>MAPI: Re-enable reconciles
  Note over MAC,CAPI: Track via generation-based sync status

Loading

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

I twitch my ears at docs so neat,
A lattice of flows, precise and sweet.
From MAPI burrows to CAPI plains,
We hand off seeds through careful chains.
With gates and guards, we hop in line—
Migration done, carrots align! 🥕

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title succinctly describes the primary change by stating that a mapi to capi migration subagent is being added, directly reflecting the pull request’s goal of introducing this new experimental subagent.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[theobarberbany]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

.claude/agents/mapi-capi-migration-expert.md (1)

35-47: Fix nested list indentation to satisfy markdownlint MD007.

markdownlint (MD007) is flagging these bullet items because they’re indented with four leading spaces instead of two. Aligning to the two-space convention clears the lint warning and keeps nested lists rendering correctly.

--    - **Machine Migration**: `pkg/controllers/machinemigration/`
--    - **MachineSet Migration**: `pkg/controllers/machinesetmigration/`
+-  - **Machine Migration**: `pkg/controllers/machinemigration/`
+-  - **MachineSet Migration**: `pkg/controllers/machinesetmigration/`
 - **Sync Controllers**:
--    - **Machine Sync**: `pkg/controllers/machinesync/`
--    - **MachineSet Sync**: `pkg/controllers/machinesetsync/`
+-  - **Machine Sync**: `pkg/controllers/machinesync/`
+-  - **MachineSet Sync**: `pkg/controllers/machinesetsync/`
 - **Conversion Logic**:
--    - **Library Root**: `pkg/conversion/`
--    - **MAPI to CAPI**: `pkg/conversion/mapi2capi/`
--    - **CAPI to MAPI**: `pkg/conversion/capi2mapi/`
--    - **Fuzz Testing**: `pkg/conversion/test/`
+-  - **Library Root**: `pkg/conversion/`
+-  - **MAPI to CAPI**: `pkg/conversion/mapi2capi/`
+-  - **CAPI to MAPI**: `pkg/conversion/capi2mapi/`
+-  - **Fuzz Testing**: `pkg/conversion/test/`
 - **Admission Policies (VAP)**:
--    - **Manifests**: `manifests/` (shipped via transport `ConfigMap`)
+-  - **Manifests**: `manifests/` (shipped via transport `ConfigMap`)

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to data retention organization setting

📥 Commits

Reviewing files that changed from the base of the PR and between 2a0af92 and 515824f.

📒 Files selected for processing (1)

• .claude/agents/mapi-capi-migration-expert.md (1 hunks)

🧰 Additional context used

🪛 markdownlint-cli2 (0.18.1)

.claude/agents/mapi-capi-migration-expert.md

36-36: Unordered list indentation
Expected: 2; Actual: 4

(MD007, ul-indent)

---

37-37: Unordered list indentation
Expected: 2; Actual: 4

(MD007, ul-indent)

---

39-39: Unordered list indentation
Expected: 2; Actual: 4

(MD007, ul-indent)

---

40-40: Unordered list indentation
Expected: 2; Actual: 4

(MD007, ul-indent)

---

42-42: Unordered list indentation
Expected: 2; Actual: 4

(MD007, ul-indent)

---

43-43: Unordered list indentation
Expected: 2; Actual: 4

(MD007, ul-indent)

---

44-44: Unordered list indentation
Expected: 2; Actual: 4

(MD007, ul-indent)

---

45-45: Unordered list indentation
Expected: 2; Actual: 4

(MD007, ul-indent)

---

47-47: Unordered list indentation
Expected: 2; Actual: 4

(MD007, ul-indent)

[openshift-ci]

@theobarberbany: all tests passed!

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

[RadekManak]

I feel like subagent is a bad abstraction for this. You probably want a /command or skill. I am not sure is much benefit of this compared to what's in AGENT.md a what Claude can figure out from search. Have you tried it?

[theobarberbany]

I am not sure is much benefit of this compared to what's in AGENT.md a what Claude can figure out from search.

This was a reaction to having to tell claude to please read and do what's in AGENT.md 😢 The idea is as AGENT.md gets longer (and claude treats it like a suggestion rather than a set of instructions), a sub agent with fresh context should behave better.

Also, having the main thread aware of the migration when not doing migration work is wasteful.

However, I've not extensively tested this. Maybe a skill is better, I wasn't aware of them when writing this ~ a month ago (just checked, they weren't released 🤣)

I'll have a play with converting to a skill + check back!

[openshift-bot]

Issues go stale after 90d of inactivity.

Mark the issue as fresh by commenting /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.
Exclude this issue from closing by commenting /lifecycle frozen.

If this issue is safe to close now please do so with /close.

/lifecycle stale

[theobarberbany]

/remove-lifecycle stale.

[damdo]

/approve

Thanks @theobarberbany

/assign @RadekManak

[openshift-ci]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: damdo

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [damdo]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[damdo]

/remove-lifecycle stale