---
name: migrate-repo-wide
description: Coordinates a repo-wide mechanical migration (rename X → Y across N files, bump dependency version across a monorepo, port a deprecated API call site by site) by dispatching the change to Claude Code's bundled `/batch` skill, which fans out into 5-30 worktree-isolated subagents that each open an independent pull request. Use only for migrations that are (a) mechanical, (b) describable in one instruction, and (c) safely partitionable into independent file sets.
when_to_use: |
  Trigger phrases: "/maxvision-orchestration:migrate-repo-wide",
  "migration repo-wide", "rename across the whole repo", "bump <pkg> in every workspace",
  "port every call site of <api>", "split this change into many PRs".
  Do NOT use for: refactors with cross-file logic dependencies, security-sensitive
  changes (run security-audit first), or work that fits in a single PR (use /fast).
disable-model-invocation: true
argument-hint: <migration description>
arguments: migration
allowed-tools: Read Grep Glob Bash(test *) Bash(git status *) Bash(git rev-parse *) Bash(git branch *) Bash(gh auth status) Bash(gh repo view *) Skill(batch)
---

# Migrate repo-wide

Argument: `$migration` (or `$ARGUMENTS`) — single-line description of the
mechanical migration. Examples:

- `rename "API_V1" → "API_V2" across all callers, leave V1 stub for 1 release`
- `bump @stripe/stripe-js from ^2 to ^3 in every package.json + run codemod`
- `replace deprecated useFetch() with useQuery() in every component under src/`

## Hard rules

1. **Confirm before dispatch.** This skill spawns 5-30 background subagents,
   each of which can open a pull request. Always show the partition plan
   and require user `sim` before invoking `/batch`.
2. **Refuse when the request is not mechanical.** If the task requires
   cross-file logic decisions, abort and recommend `/maxvision-orchestration:plan-phase`
   instead. Mechanical = same transformation rule applied to many files.
3. **Refuse when scope cannot be partitioned.** A migration that needs all
   files in one atomic commit (e.g. tightly coupled type refactor) does
   NOT fit `/batch`. Recommend a single PR via `/maxvision-orchestration:execute-phase`.
4. **Require git + gh.** `/batch` opens real pull requests. Abort with a
   structured error when either is missing.
5. **Stay under the cap.** Hard ceiling is 30 partitions per `/batch`
   invocation (matches the upstream `/batch` documented maximum). Larger
   migrations must be split into multiple invocations by file subtree.

## Render-time preflight

- Repo root present:  !`git rev-parse --show-toplevel 2>/dev/null || echo "NOT_A_GIT_REPO"`
- Working tree clean: !`test -z "$(git status --porcelain 2>/dev/null)" && echo "CLEAN" || echo "DIRTY"`
- gh authenticated:   !`gh auth status >/dev/null 2>&1 && echo "GH_OK" || echo "GH_MISSING"`
- Default branch:     !`gh repo view --json defaultBranchRef -q .defaultBranchRef.name 2>/dev/null || echo "main"`

## Workflow

### 1. Honor preflight

Abort with a structured response if any of:

- `NOT_A_GIT_REPO` — recommend running from a git repository.
- `DIRTY` — recommend stashing or committing before dispatching `/batch`
  (each worktree branches from `origin/HEAD` per the worktree settings).
- `GH_MISSING` — recommend `gh auth login`. `/batch` cannot open PRs
  without authenticated `gh`.

### 2. Classify the request

Re-read `$migration`. Decide:

| Signal | Decision |
| --- | --- |
| Same regex/AST transformation across N files | **mechanical**, proceed |
| Bumping a single dependency version across a monorepo | **mechanical**, proceed |
| Removing a deprecated API call site by site | **mechanical**, proceed |
| Refactor that adds new types or restructures modules | **logical**, abort + recommend `plan-phase` |
| Cross-file ordering matters (must change file A before file B) | **non-partitionable**, abort + recommend `execute-phase` |
| Single-file scope | **wrong tool**, recommend `/maxvision-orchestration:fast` |

If the request is ambiguous, ASK ONE clarifying question via the main
thread (e.g. "Is this purely a rename, or should I also update the
generated types?") before continuing. Do not silently assume.

### 3. Propose partition

Identify the candidate file set with Grep/Glob (NOT modifying anything).
Group into independent chunks. Aim for ~5-10 files per chunk so each
worktree's PR is reviewable. Cap at 30 chunks total.

Render the partition plan as a table for the user:

```
Migration:      <one-line summary of $migration>
File pattern:   <glob or grep pattern used>
Total files:    <N>
Partitions:     <K chunks, ~F files each>
Cap respected:  <K> ≤ 30 ✓
Each chunk →    1 worktree (auto-isolated by /batch) → 1 pull request
```

### 4. Request confirmation

```
About to dispatch /batch with <K> partitions.
Each partition will:
  - Open its own git worktree under .claude/worktrees/
  - Apply the rule "<migration>" to the assigned file chunk
  - Open a pull request against <default-branch>

Total PRs: <K>
Total token cost: approximately K × <per-chunk-estimate>

Proceed? [sim/skip]
```

Wait for explicit `sim`. On `skip`, exit 0 with `{"status":"skipped"}`.

### 5. Invoke /batch

Forward the rendered partition plan + the migration rule as a single
prompt to the bundled `/batch` skill. `/batch` is responsible for the
actual worktree creation and PR opening; this skill only handles
classification, partitioning, and confirmation.

```text
Use Skill(batch) with:
  - migration_rule: "<verbatim $migration>"
  - partitions: <serialized K-element file-chunk list>
  - branch_prefix: "maxv-migrate-<short-name>-"
  - pr_title_template: "<migration short-name>: chunk {N}/<K>"
```

### 6. Monitor and report

After dispatch, surface to the user:

- Where to watch progress: `claude agents` (each batch session appears
  as a row with token count and PR status dot).
- Where to inspect partial state: `~/.claude/worktrees/` (or wherever
  `WorktreeCreate` hook redirects).
- How to abort: `gh pr close` on individual PRs, or `claude stop <id>`
  via Agent View for individual subagent sessions.

Append a single line to `~/.claude/projects/<workspace>/maxv-orchestration.log`:

```
2026-05-16T20:45:00Z  migrate-repo-wide  <K> partitions  rule=<short>  ok
```

## Output JSON

When dispatch succeeds:

```json
{
  "status": "dispatched",
  "migration": "<verbatim>",
  "partitions": <K>,
  "next_step": "Monitor via `claude agents` — each row corresponds to one partition"
}
```

When aborted at preflight or classification:

```json
{
  "status": "aborted",
  "reason": "NOT_A_GIT_REPO | DIRTY | GH_MISSING | non_mechanical | non_partitionable | single_file",
  "recommended_alternative": "/maxvision-orchestration:fast | plan-phase | execute-phase"
}
```

## Guardrails (mirroring orchestrate Phase 7)

- Never invoke `/batch` without explicit user `sim`.
- Never invoke `/batch` when working tree is dirty (would conflict with
  worktree creation in some git configs).
- Never exceed K=30 partitions in one invocation — split larger migrations
  by file subtree and run sequentially.
- Never auto-merge generated PRs. Each PR must be reviewed by a human
  (or by `maxv-code-reviewer` invoked separately).

## Related skills

- [`/fast`](../fast/SKILL.md) — single-file or trivial change
- [`/quick`](../quick/SKILL.md) — multi-file change, single PR
- [`execute-phase`](../execute-phase/SKILL.md) — coordinated multi-step
  change within one phase (uses wave-of-4 subagent dispatch, not `/batch`)
- [`plan-phase`](../plan-phase/SKILL.md) — when the work is logical
  rather than mechanical