Migrate To Rn

migrate-to-rn

Use this skill when the user asks to run the migrated source command migrate-to-rn.

Command Template

Orchestrator — React Native Migration Pipeline

You ARE the orchestrator. You set up worktrees, spawn agents, present gates, and open PRs. You do NOT read agent files to follow their steps yourself.

Pre-flight Acknowledgment

• I will run the skill extras check (jq, agent-device, agent-browser) and install anything missing before Step 0
• I will spawn agents via the Agent tool with the appropriate subagent_type
• I will NOT execute the plan/execute/verify steps myself
• I will pass the worktree absolute path in each agent's prompt
• I will present artifacts to the user at gates before proceeding
• I will never skip a pipeline phase — Plan → Execute → Verify always run in order, even if a previous agent produced implementation files as a side effect
• I will never commit, push, or create a PR without explicit human approval at the Final Gate — verification passing is NOT approval; only the user's confirmation is

Include

Use the Read tool to load:

1. .claude/rules/orchestrator-guardrails.md
2. .claude/rules/rn-migration.md

Pre-flight: Skill extras

Assumes Blade dev already works (yarn install, Xcode, pod install, yarn start:ios, etc.).

Before Step 0, verify these skill-only tools are on PATH:

command -v jq || echo 'MISSING: jq'
command -v agent-device || echo 'MISSING: agent-device'
command -v agent-browser || echo 'MISSING: agent-browser'

If any check fails: install the missing tool(s), run any post-install setup they require, then re-check. Do not proceed to Step 0 until all three pass.

Optional later: gh authenticated — only needed at Final Gate for gh pr create.

Input

User provides one or more component names (e.g., "add native support to Drawer" or "migrate Drawer, InfoGroup to native").

Output

• One PR per component on branch feat/blade-rn/{Name}
• Artifacts in .claude/worktrees/{Name}/.claude/artifacts/{Name}/
• Batch status in .claude/artifacts/batch-status.md (main checkout)

Step 0: Setup

0.1 Parse Input

Extract component name(s). If multiple, process as a batch.

0.2 Validate Each Component

For each component:

ls packages/blade/src/components/{Name}/ > /dev/null 2>&1 && echo "EXISTS" || echo "NOT FOUND"

If not found → report error, skip that component.

0.3 Check Native Status

Don't classify on bare throwBladeError — validation-only files (Tabs, Avatar, AccordionButton) are REAL. Use the Plan agent's genuine-stub detection so the gate and Plan phase agree.

# Genuine stub = small file whose body is essentially just a throwBladeError (no real render tree/hooks).
# Validation-only files that use throwBladeError are large, so a line-count threshold separates them.
grep -rl "throwBladeError" packages/blade/src/components/{Name}/ --include="*.native.tsx" | while read -r f; do
  if [ "$(wc -l < "$f")" -lt 40 ]; then echo "STUB: $f"; else echo "REAL: $f"; fi
done

• Any STUB:, or no .native.tsx at all → needs migration (proceed)
• Mix of STUB: and REAL: → partial migration (proceed — Plan only creates/replaces the stub/missing files, skips REAL ones)
• All REAL: → skip: "Already has native support"

0.4 Allocate Slots — Ports, Devices, Sessions

Number the surviving components 1..N (in input order). Assign per slot:

Cap at 5 parallel slots (machine RAM/CPU limit — each booted simulator uses ~2-3 GB). If batch > 5, queue remaining components and process them after the first batch's verify phase completes.

This works because agent-device natively supports multi-worktree RN development: each simulator gets its own Metro port written to per-simulator debug server settings on open, so bundles don't conflict. See agent-device help react-native for details.

0.5 Create Worktrees

For each component in the batch:

git worktree add -B feat/blade-rn/{Name} .claude/worktrees/{Name} origin/master

0.6 Ensure Dependencies in Worktrees

cd .claude/worktrees/{Name} && yarn install --frozen-lockfile

Or if APFS clone available:

cp -Rc node_modules .claude/worktrees/{Name}/node_modules 2>/dev/null || (cd .claude/worktrees/{Name} && yarn install --frozen-lockfile)

0.7 Shared App Build

The Storybook .app binary only needs to be built once — all worktrees share the same native code; only JS differs (served by each worktree's own Metro). Build from the first slot's worktree:

cd .claude/worktrees/{Name1}/packages/blade && yarn start:ios

This builds, installs, and launches the app on the first simulator (slot 1's device). Run via Bash tool with run_in_background: true.

Wait for the build to complete and the app to appear:

agent-device wait text "COMPONENTS" 60000 --session rn-{Name1}

For slots 2..N, the app is already installed on the first simulator. To get it on additional simulators, install the built .app artifact:

# Find the built .app from the Xcode derived data
APP_PATH=$(find ~/Library/Developer/Xcode/DerivedData -name "blade.app" -path "*/Build/Products/Debug-iphonesimulator/*" -maxdepth 5 2>/dev/null | head -1)

# For each additional slot i (2..N):
agent-device open org.reactjs.native.example.blade \
  --platform ios --device "{iOSDevice_i}" \
  --session rn-{Name_i} --metro-port {MetroPort_i} --relaunch

If the app isn't found on a secondary simulator, install it explicitly:

agent-device install org.reactjs.native.example.blade "$APP_PATH" \
  --platform ios --device "{iOSDevice_i}"
agent-device open org.reactjs.native.example.blade \
  --platform ios --device "{iOSDevice_i}" \
  --session rn-{Name_i} --metro-port {MetroPort_i} --relaunch

Note: Metro is NOT started by the orchestrator — each Verify agent starts its own Metro on the assigned port inside its worktree.

0.8 Set Per-Simulator Metro Port (Port Isolation)

CRITICAL: Without this step, reloads on any simulator will fetch the JS bundle from port 8081 (the default), causing cross-contamination between worktrees during parallel visual verification.

After the app is installed on all simulators, write the correct Metro port into each simulator's app preferences using xcrun simctl spawn:

# Slot 1 (port 8081) — default, no override needed

# For slots 2..N:
xcrun simctl spawn "{iOSDevice_2}" defaults write org.reactjs.native.example.blade RCT_jsLocation "localhost:{MetroPort_2}"
xcrun simctl spawn "{iOSDevice_3}" defaults write org.reactjs.native.example.blade RCT_jsLocation "localhost:{MetroPort_3}"
# ... repeat for each additional slot

This writes into NSUserDefaults for that simulator's app container, so even when the app reloads (shake gesture, error recovery, Fast Refresh reconnect), it fetches from the correct Metro port — not 8081.

Verify this worked: Each Verify agent should see its own worktree's component in the Storybook list, not another slot's component.

⛔ HARD GATE: Steps 0.7 and 0.8 are MANDATORY before spawning Verify agents. Do NOT proceed to Step 4 (Verify Phase) without completing the shared app build and port isolation. The app binary (native shell) can be built as early as Step 0 since RN migrations only add .native.tsx (JS) files — Metro serves the latest JS dynamically at runtime. Building early lets the ~5min build run in parallel with Plan/Execute, saving wall-clock time. Only rebuild after Execute if a new native dependency was added (new pod/native module) — rare for RN migrations. TS checks and unit tests can run without the app, but visual verification requires it. If the app build is skipped, Verify agents MUST be told --skip-visual or visual results are invalid. Alternatively, the first Verify agent can build the app if the orchestrator hasn't — but only one agent should build, not all of them.