From ad-migration
Use when applying approved candidates from a refactor-mart markdown plan
npx claudepluginhub accelerate-data/migration-utility<plan-file> stg|int# Refactor Mart Apply one approved wave from a `/refactor-mart-plan` markdown plan. ## Arguments Manual mode: Coordinator mode: In Claude Code slash commands, `$0` is the first user-supplied argument. Manual mode is active only when the positional arguments are exactly: - `$0 = <refactor-mart-plan-file>` - `$1 = stg|int` Coordinator mode is active only when the positional arguments are exactly: - `$0 = <migrate-mart-plan-file>` - `$1 = <stage-id>` - `$2 = <worktree-name>` - `$3 = <base-branch>` - `$4 = <refactor-mart-plan-file>` - `$5 = stg|int` Modes: - `stg`: approved `Type:...
Apply one approved wave from a /refactor-mart-plan markdown plan.
Manual mode:
/refactor-mart <plan-file> stg|int
Coordinator mode:
/refactor-mart <migrate-mart-plan-file> <stage-id> <worktree-name> <base-branch> <refactor-mart-plan-file> stg|int
In Claude Code slash commands, $0 is the first user-supplied argument.
Manual mode is active only when the positional arguments are exactly:
$0 = <refactor-mart-plan-file>$1 = stg|intCoordinator mode is active only when the positional arguments are exactly:
$0 = <migrate-mart-plan-file>$1 = <stage-id>$2 = <worktree-name>$3 = <base-branch>$4 = <refactor-mart-plan-file>$5 = stg|intModes:
stg: approved Type: stg candidates only.int: approved Type: int and Type: mart candidates only.Never apply unapproved candidates. Never edit candidates outside the selected mode. skipped is a final-summary category only; do not write Execution status: skipped.
PLAN_NOT_FOUND.stg or int, fail with INVALID_MODE.manifest.json is missing, fail with MANIFEST_NOT_FOUND.dbt/dbt_project.yml is missing, fail with DBT_PROJECT_MISSING and tell the user to run ad-migration setup-target.refactor-mart-<mode>-<plan-stem>.<epoch_ms>-<random_8hex> (for example 1743868200123-a1b2c3d4). Use it as the suffix for every artifact written by this run, including .migration-runs/pr-body.<run_id>.md.## Arguments contract above to determine whether this is manual mode or coordinator mode. Do not infer coordinator mode from $0 alone; the full positional shape must match exactly.${CLAUDE_PLUGIN_ROOT}/scripts/stage-worktree.sh for deterministic worktree setup.
Coordinator mode: read Branch:, Worktree name:, and Base branch: from the matching stage section in the migrate-mart plan, then run:
"${CLAUDE_PLUGIN_ROOT}/scripts/stage-worktree.sh" "<branch>" "<worktree-name>" "<base-branch>"
Use the returned worktree_path for all reads, writes, commits, and prompts.
Manual mode: derive a stable branch name from the run slug, resolve the remote default branch, and call the same helper with those explicit values.
## Stage <stage-id> checklist in <migrate-mart-plan-file>. After each stage substep or candidate result, update only that checklist, then commit the plan update together with the artifact or catalog change that caused it.$0 and the nested refactor-mart plan file from $4 in that working directory. Manual mode: read the refactor-mart plan file from $0.Select only sections with exact checked approval syntax:
- [x] Approve: yes.
| Mode | Select | Leave unchanged |
|---|---|---|
stg | Type: stg | Type: int, Type: mart, unapproved candidates |
int | Type: int, Type: mart | Type: stg, unapproved candidates |
intCheck dependencies before any dbt edit or apply-skill invocation.
Block the selected candidate in the plan when:
Depends on: is missing, empty, malformed, ambiguous, or not exactly none or candidate IDs;Execution status: applied.Include the metadata problem, or each missing/unsatisfied dependency ID and its actual status, in exactly one Blocked reason: bullet.
Process selected candidates in plan order. After each apply-skill invocation, reread the plan before gating the next selected candidate so a newly applied candidate can satisfy downstream dependencies in the same wave.
After the guards pass, perform selected plan and dbt edits directly in the active working directory. Do not ask for permission before dispatching a selected candidate.
| Mode | Dispatch |
|---|---|
stg | applying-staging-candidate <plan-file> <candidate-id> |
int | applying-mart-candidates <plan-file> <candidate-id> |
Ownership:
| Owner | Writes |
|---|---|
/refactor-mart | dependency-blocked candidate statuses and reasons |
| apply skill | dbt edits, candidate-scoped validation, non-dependency input blocks |
After each candidate is processed, reread that candidate section. If itsExecution status: is applied or failed, it must contain exactly oneValidation result: bullet. If its Execution status: is blocked, it must contain exactly one Blocked reason: bullet. Fix the selected candidate section
before moving to the next candidate.
After all selected candidates are processed, reread the plan and report:
refactor-mart <mode> complete -- <plan-file>
applied: <n>
failed: <n>
blocked: <n>
skipped: <n>
List blocked candidate IDs with dependency or metadata reasons. List failed candidate IDs with validation summaries. Skipped means approved candidates not selected for the current mode plus unapproved candidates in the current wave; blocked candidates are not skipped.
After successful candidate work is committed and pushed, always open or update a PR:
"${CLAUDE_PLUGIN_ROOT}/scripts/stage-pr.sh" "<branch>" "<base-branch>" "<title>" ".migration-runs/pr-body.<run_id>.md"
Report the PR number and URL. In manual mode, tell the human to review and merge the PR. In coordinator mode, return the PR metadata to the coordinator and do not ask any question.
If on a feature branch, also tell the user: "Once the PR is merged, run /cleanup-worktrees to remove the worktree and branches."