---

name: config-migrator description: Migrates codex configuration files from v2.0 push-based sync to v3.0 pull-based retrieval format with automatic backups model: claude-haiku-4-5

Config Migrator Skill

<CRITICAL_RULES>

1. ALWAYS create backup before modifying configuration
2. NEVER overwrite without backup confirmation
3. ALWAYS validate new configuration before saving
4. STOP immediately if validation fails
5. PRESERVE all settings - no data loss during migration </CRITICAL_RULES>

2. Analyze & Plan

   • Extract v2.0 settings (organization, codex_repo, sync_patterns)
   • Plan v3.0 structure with sources array
   • Map sync_patterns to permission defaults if present
   • Calculate what changes will be made

3. Create Backup

   • Generate backup filename with timestamp
   • Copy current config to backup location
   • Verify backup created successfully
   • Log backup path

4. Convert Configuration

   • Build v3.0 config structure
   • Add default source for codex repository
   • Convert sync_patterns to permission guidance (as comment)
   • Preserve organization, codex_repo, version fields
   • Add performance defaults

5. Validate

   • Check JSON syntax
   • Verify required fields present
   • Validate source configuration
   • Test that config is loadable

6. Apply or Preview

   • If dry_run: show diff and exit
   • If not dry_run and not skip_prompts: ask for confirmation
   • Write new configuration
   • Verify write successful

7. Test

   • Attempt to load new configuration
   • If test fails: restore from backup
   • If test succeeds: report success

<COMPLETION_CRITERIA>

• Configuration successfully migrated OR dry-run preview shown
• Backup created (unless dry-run)
• Validation passed
• Migration summary provided </COMPLETION_CRITERIA>

./skills/config-migrator/scripts/migrate-config.sh "$config_path" "$dry_run" "$force" "$backup_path"

The script returns JSON output with migration results.

1. Summary of what changed
2. Backup location for rollback
3. Next steps:
   • Test retrieval: /fractary-codex:fetch @codex/project/path
   • View cache: /fractary-codex:cache-list
   • Read migration guide: docs/MIGRATION-PHASE4.md
4. Rollback command if needed

<ERROR_HANDLING>

• Config not found: Inform user, ask if they want to create new v3.0 config
• Invalid JSON: Report syntax error, provide line number if possible
• Backup fails: STOP, do not proceed with migration
• Validation fails: Restore backup, report validation errors
• Write fails: Keep backup, report permissions error </ERROR_HANDLING>