§ reference · skill

migrate-to-guidance

One-shot move from inline `CLAUDE.md` files to the `.rpiv/guidance/` shadow tree — transforms cross-references along the way.

arguments --delete-originals

§ 01 · purpose

Purpose

Converts a project that already uses inline CLAUDE.md files into the shadow-tree layout consumed by annotate-guidance. The migration relocates every file to .rpiv/guidance/<path>/architecture.md and rewrites internal references so links keep working after the move.

§ 02 · when to use

When to use it

A project already has inline CLAUDE.md files from annotate-inline and you want shadow-tree layout instead.
You're consolidating scattered CLAUDE.md files into one place.
Skip when no CLAUDE.md files exist — there is nothing to migrate.

§ 03 · inputs

Inputs

Name	Required	Source
`--delete-originals (flag)`	no	Pass to remove the original `CLAUDE.md` files after a successful move
`--force (flag)`	no	Overwrite conflicting target files

§ 04 · outputs

Outputs

Artifact	Path	Format
Shadow guidance tree	`.rpiv/guidance/<path>/architecture.md`	markdown (format-preserved from source)

§ 05 · key steps

Key steps

Pre-flight glob + conflict scan Why: Globs **/CLAUDE.md and inspects .rpiv/guidance/ so the user sees, up-front, what will move and what would collide before any write happens.
Dry-run preview — file list, conflicts, warnings Why: The migration script emits a JSON plan; the skill renders it as a table the user signs off on. Catches missed files and dangerous overwrites before the destructive run.
Decide on --delete-originals and --force Why: Flags are explicit decisions, not defaults. Forces the user to acknowledge the destructive shape of the run.
Execute migration script; parse JSON results Why: All file operations stay in the script — the skill never moves files by hand. Keeps the operation reversible and consistent across runs.
Repair unresolved prose references Why: Some cross-references the script can't rewrite automatically; the skill offers a contextual fix-up pass using project structure knowledge to finish the link rewrites.

§ 06 · related skills

upstream annotate-inline

downstream annotate-guidance