---
name: migrate-to-guidance
description: Migrate existing CLAUDE.md files to .rpiv/guidance/ system. Finds all CLAUDE.md files, transforms references, and creates architecture.md files in the guidance shadow tree.
argument-hint: [--delete-originals]
allowed-tools: Bash, Read, Glob
---

# Migrate CLAUDE.md to Guidance

You are tasked with migrating a project's existing `CLAUDE.md` files (typically created by `/skill:annotate-inline`) into the `.rpiv/guidance/` system.

The migration relocates files from in-place `CLAUDE.md` to `.rpiv/guidance/{path}/architecture.md` and transforms internal cross-references.

## Steps to follow:

1. **Pre-flight check:**
   - Use Glob to find all `**/CLAUDE.md` files in the project
   - If none are found, inform the user: "No CLAUDE.md files found in this project. Nothing to migrate." and stop
   - If `.rpiv/guidance/` already exists, note this — there may be conflicts

2. **Dry run — preview the migration:**
   - Run the migration script in dry-run mode:
     ```
     node scripts/migrate.js --project-dir "${CWD}" --dry-run
     ```
   - Parse the JSON output from stdout and present a migration plan to the user:
     ```
     ## Migration Plan

     Found [N] CLAUDE.md files to migrate:

     | Source | Target | Lines |
     |--------|--------|-------|
     | CLAUDE.md | .rpiv/guidance/architecture.md | 45 |
     | src/core/CLAUDE.md | .rpiv/guidance/src/core/architecture.md | 78 |
     | ... | ... | ... |
     ```
   - If there are **conflicts** (targets that already exist), list them:
     ```
     ### Conflicts (targets already exist):
     - .rpiv/guidance/src/core/architecture.md

     Use --force to overwrite these.
     ```
   - If there are **warnings** (unresolved prose references), list them:
     ```
     ### Warnings:
     - .rpiv/guidance/architecture.md line 23: Prose reference may need manual update
     ```
   - Ask the user for confirmation before proceeding. Ask whether they want to:
     - Delete the original CLAUDE.md files after migration (`--delete-originals`)
     - Overwrite existing conflicts (`--force`)

3. **Execute the migration:**
   - Build the command based on user choices:
     ```
     node scripts/migrate.js --project-dir "${CWD}" [--delete-originals] [--force]
     ```
   - Run the migration and parse the JSON output
   - Present the results:
     ```
     ## Migration Complete

     | Source | Target | Lines | Refs Updated |
     |--------|--------|-------|--------------|
     | CLAUDE.md | .rpiv/guidance/architecture.md | 45 | 3 |
     | src/core/CLAUDE.md | .rpiv/guidance/src/core/architecture.md | 78 | 1 |
     | ... | ... | ... | ... |

     Total: [N] files migrated
     [Originals deleted: yes/no]
     ```

4. **Post-migration:**
   - If warnings exist about unresolved prose references:
     - Read the affected guidance files
     - Offer to fix the remaining references using contextual knowledge of the project structure
   - Suggest next steps:
     - "Run `claude` in the project and read a source file to verify guidance injection works"
     - If originals were not deleted: "You can delete the original CLAUDE.md files once you've verified the migration"
     - "If you were using `/skill:annotate-inline`, you can now use `/skill:annotate-guidance` for future annotations"

## Important notes:
- The migration script handles all file operations — do not manually copy or move CLAUDE.md files
- Content format is preserved as-is (same markdown structure, same `<important if>` blocks)
- Only cross-references between files are transformed (`CLAUDE.md` paths → `.rpiv/guidance/` paths)
- The script outputs JSON to stdout — parse it for structured results
- Debug logs go to stderr (visible with `claude --verbose`)