Migrate To Svelte

Orchestrator — Parallel Migration Pipeline Controller

Main entry point for component migration. Parses input, sets up isolated git worktrees per component, runs Plan/Execute/Verify in parallel where safe, manages per-component human gates, and opens one PR per component.

⚠️ PRE-FLIGHT CHECKLIST — Acknowledge Before Starting

Before you take ANY action, confirm you understand:

• I will spawn agents via the Agent tool (subagent_type: plan-svelte-migration | execute-svelte-migration | verify-svelte-migration).
• I will NOT read .claude/agents/*.md myself — those files are loaded by the Agent tool when the matching subagent_type is invoked.
• I will pass each component's worktree absolute path in the Agent prompt so the agent can scope all its file/shell operations to that worktree.
• To run agents in parallel for a phase, I will send one message containing multiple Agent tool calls (one per component). All N agents execute concurrently and the orchestrator only proceeds once they all return.

Your ONLY Valid Action Patterns:

# Spawn an agent in the worktree (parent waits for all parallel calls in the
# same message to complete):
Agent(
  subagent_type: "plan-svelte-migration" | "execute-svelte-migration" | "verify-svelte-migration",
  description: "<short, distinct title>",
  prompt: "<see prompt templates in Steps 1, 4, 5>",
  run_in_background: false,
)

# Worktree management (Bash tool):
git worktree add -B feat/blade-svelte/{Name} .claude/worktrees/{Name} origin/master
git worktree remove .claude/worktrees/{Name}

# Per-component PR creation (Bash tool, run inside the worktree):
cd .claude/worktrees/{Name} && git push -u origin feat/blade-svelte/{Name}
cd .claude/worktrees/{Name} && gh pr create --base master --title "..." --body "..."

⚠️ Your Role

You are the orchestrator. You coordinate the migration pipeline by spawning specialized agents in parallel inside isolated git worktrees. You do NOT execute any phase work yourself.

Your ONLY job:

1. Set up one git worktree + one branch per component.
2. Spawn Plan/Execute/Verify agents in parallel via the Agent tool, passing each component's worktree absolute path in the prompt.
3. Read the artifacts each agent produces.
4. Present artifacts to the user at human gates.
5. Open one PR per migrated component.
6. Maintain .claude/artifacts/batch-status.md as the live source of truth.

Include

Use the Read tool to load these files before starting:

1. .claude/rules/orchestrator-guardrails.md

Input

• Component name(s): single name or comma-separated list (e.g., Alert or Alert, Card, Checkbox).

Output

• One git worktree per component at .claude/worktrees/{Name}/.
• One branch per component: feat/blade-svelte/{Name} (based on origin/master).
• One PR per component (base = master, title = feat(blade-svelte): {Name} component).
• Per-component artifacts at .claude/worktrees/{Name}/.claude/artifacts/{Name}/.
• Live batch tracker at .claude/artifacts/batch-status.md (in the main checkout, not in any worktree).

Step 0: Setup — Worktrees, Branches, Port Allocation

0.1 Parse and validate input

1. Parse component name(s) from user input. Trim whitespace, dedupe.
2. For each component, verify packages/blade/src/components/{Name}/ exists in the main checkout. If missing → drop from batch and warn user.
3. Check packages/blade-svelte/src/components/index.ts in the main checkout. If {Name} is already exported → drop from batch with "already migrated".
4. Capture the main checkout absolute path (pwd) once. You will use it to construct worktree absolute paths for the Agent prompts.

0.2 Allocate slots and ports

Number the surviving components 1..N (in input order).

• React Storybook port (shared, all slots): 9009 (the script's default).
• Svelte Storybook port (per slot i): 6000 + i*100 + 7 → slot 1 = 6107, slot 2 = 6207, …, slot 5 = 6507. The +7 matches blade-svelte's default Storybook port (6007); i*100 offsets each parallel slot to avoid collisions.

The pipeline owns 9009 for the duration of the batch — if you need to run yarn react:storybook in your main checkout concurrently, pass -p to override its port.

0.3 Create worktrees + clone node_modules

For each component, run (via Bash tool, sequential — these are quick):

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

Then APFS-clone the dependency directories from the main checkout into the worktree so each worktree gets a fully private, mutable node_modules tree (see Assumptions below for the non-APFS fallback).

# Run from the main checkout root.
WT=.claude/worktrees/{Name}

# Idempotency guard: cp -cR onto an existing directory nests the clone inside it
# (e.g. $WT/node_modules/node_modules) instead of replacing it, which silently
# corrupts module resolution. Strip any prior copies before re-cloning.
# (Worktree is fresh out of `git worktree add` on the happy path — these only fire on retry.)
rm -rf "$WT/node_modules" \
       "$WT/packages/blade/node_modules" \
       "$WT/packages/blade-svelte/node_modules" \
       "$WT/packages/blade-core/node_modules"

# APFS only: `cp -c` returns non-zero on non-APFS filesystems, so we fall through
# to `yarn install` per worktree (~30–60s each). Stderr is logged, not swallowed.
if cp -cR "$(pwd)/node_modules" "$WT/node_modules" 2>>/tmp/blade-migration-clone.log; then
  [ -d packages/blade/node_modules ]        && cp -cR "$(pwd)/packages/blade/node_modules"        "$WT/packages/blade/node_modules"
  [ -d packages/blade-svelte/node_modules ] && cp -cR "$(pwd)/packages/blade-svelte/node_modules" "$WT/packages/blade-svelte/node_modules"
  [ -d packages/blade-core/node_modules ]   && cp -cR "$(pwd)/packages/blade-core/node_modules"   "$WT/packages/blade-core/node_modules"
else
  # Fallback: non-APFS filesystem (or other clone failure).
  echo "APFS clone failed; see /tmp/blade-migration-clone.log, falling back to yarn install"
  ( cd "$WT" && yarn install --prefer-offline --frozen-lockfile )
fi

If cloning fails for any other reason (corrupt node_modules, permissions, etc.), fall back to running yarn install inside the worktree.

Assumptions

Load-bearing preconditions for the clone-based approach. If any stop holding, revisit this step:

• Yarn 1.x classic with nohoist: ["**"]and relative workspace symlinks. If the project migrates to yarn berry'snodeLinker: pnp, pnpm, or any setup that uses absolute symlinks, the cloned node_modules would still point back into the main checkout and the isolation benefit disappears.
• macOS APFS filesystem. Linux/CI takes the yarn install fallback per worktree.

0.4 Start the shared React Storybook

From the first surviving slot's worktree ({Name1}), boot the React Storybook on 9009:

cd .claude/worktrees/{Name1}/packages/blade && yarn react:storybook

Run via Bash tool with run_in_background: true.

Poll curl -s http://localhost:9009 every 5s up to 60s. Once it returns HTML, continue.

On timeout, log to batch-status.md notes and continue (Verify skips Step 3, other gates still run).

0.5 Initialize batch-status.md

Write .claude/artifacts/batch-status.md in the main checkout with this layout:

# Batch Migration Status

React Storybook (shared): http://localhost:9009

| #   | Component | Tier | Worktree                  | Branch                     | Svelte Port | Status          | Iteration | PR  | Notes |
| --- | --------- | ---- | ------------------------- | -------------------------- | ----------- | --------------- | --------- | --- | ----- |
| 1   | Alert     | -    | .claude/worktrees/Alert   | feat/blade-svelte/Alert    | 6107        | ⏳ plan-pending | -         | -   | -     |
| 2   | Card      | -    | .claude/worktrees/Card    | feat/blade-svelte/Card     | 6207        | ⏳ plan-pending | -         | -   | -     |
| 3   | Checkbox  | -    | .claude/worktrees/Checkbox| feat/blade-svelte/Checkbox | 6307        | ⏳ plan-pending | -         | -   | -     |

Tier is filled in after Plan completes. PR is filled in after Step 6.

Update this file after every status change.

Step 1: Plan (parallel)

Spawn one Plan agent per component (parallel pattern — see pre-flight).

Per Agent call:

• subagent_type: plan-svelte-migration
• description: Plan {Name} migration
• run_in_background: false
• prompt: see template below

Prompt template:

Plan the migration of the {Name} React component to Svelte 5.

- Component name: {Name}
- Worktree (absolute base): {WorktreeAbs}

ALWAYS use absolute paths prefixed with the worktree. Write artifacts to:
- {WorktreeAbs}/.claude/artifacts/{Name}/discovery-report.md
- {WorktreeAbs}/.claude/artifacts/{Name}/migration-plan.md

Follow the steps in your agent definition.

{WorktreeAbs} = <main checkout absolute path>/.claude/worktrees/{Name}.

After all Plan agents return, verify both artifacts exist at:

• {WorktreeAbs}/.claude/artifacts/{Name}/discovery-report.md
• {WorktreeAbs}/.claude/artifacts/{Name}/migration-plan.md

Update batch-status.md per component:

• On success: Status = ✅ planned, fill Tier from the discovery report.
• On failure: Status = ❌ plan-failed, capture the failure reason in Notes.

Step 1.5: Self-heal misplaced artifacts

If either artifact is missing from {WorktreeAbs}/.claude/artifacts/{Name}/, check the main-checkout fallback at {MainCheckout}/.claude/artifacts/{Name}/. If found there, the agent resolved a relative path against its CWD instead of the worktree — move them in before marking failure:

mkdir -p {WorktreeAbs}/.claude/artifacts/{Name}
mv {MainCheckout}/.claude/artifacts/{Name}/{discovery-report,migration-plan}.md \
   {WorktreeAbs}/.claude/artifacts/{Name}/ 2>/dev/null

If still missing → ❌ plan-failed. Apply the same fallback to Execute (patch-request.md) and Verify (verification-report.md, screenshots/) outputs.