FAF Migrate - Format Version Upgrader

Purpose

Automatically upgrade

project.faf

files from older format versions to the current IANA-registered specification (v3.0.0+). Preserves all existing content while adding required modern fields.

The Goal: Painless migration from any old format to current standard. Zero data loss.

When to Use

This skill activates automatically when the user:

• Has old project.faf (format version <3.0.0)
• Sees "old format version" warning from

  faf validate

• Says "Upgrade my FAF format"
• Says "Migrate to latest version"
• Asks "How do I update my project.faf?"
• Has project.faf without IANA media type
• Wants IANA registration compliance

Trigger Words: migrate, upgrade, update, convert, modernize, latest version, IANA compliance

How It Works

Step 1: Detect Current Version

Check existing format version:

# Read current format version
grep -A2 "metadata:" project.faf | grep "format_version"

Possible versions:

• v1.x (original, pre-metadata) - deprecated
• v2.x (added metadata) - deprecated
• v3.x (IANA registered) - current

Step 2: Backup Original

Always backup before migration:

# Create backup
cp project.faf project.faf.backup

# Verify backup exists
ls -la project.faf.backup

Step 3: Execute Migration

Run the migration command:

faf migrate

This command (from faf-cli v5.0.6):

• Detects current version
• Determines required upgrades
• Adds missing fields
• Updates format version
• Preserves all existing content
• Creates backup automatically

Step 4: Verify Migration

Check migration succeeded:

# Validate new format
faf validate

# Check new version
grep -A2 "metadata:" project.faf | grep "format_version"
# Should show: 3.0.0 or higher

# Verify IANA media type added
grep "iana_media_type" project.faf
# Should show: application/vnd.faf+yaml

Step 5: Test & Score

After migration, verify everything works:

# Score the migrated file
faf score

# Sync if you have CLAUDE.md
faf bi-sync

# Final validation
faf validate

Migration Paths

v1.x → v3.0.0

What v1.x looked like:

name: my-project
description: What it does
language: TypeScript
framework: React
testing: Jest

What gets added:

# Original content preserved
name: my-project

# 'description' renamed to 'purpose' (semantic clarity)
purpose: What it does

# Metadata section added (v3.0.0 requirement)
metadata:
  format_version: 3.0.0
  iana_media_type: application/vnd.faf+yaml
  created: 2025-11-02
  migrated_from: 1.0.0

# Version field added (semver)
version: 1.0.0

# Architecture section added (v3.0.0 structure)
architecture:
  type: web-app  # Inferred from context
  language: TypeScript  # Moved from root

# Stack section added (v3.0.0 structure)
stack:
  framework: React  # Moved from root

# Testing section restructured
testing:
  framework: Jest  # Moved from root

Migration time: ~50ms

v2.x → v3.0.0

What v2.x looked like:

name: my-project
purpose: What it does
version: 1.0.0

metadata:
  format_version: 2.5.0
  created: 2024-06-15

architecture:
  type: web-app
  language: TypeScript

stack:
  framework: React 18

What gets added:

# All original content preserved

# metadata section enhanced
metadata:
  format_version: 3.0.0  # Updated from 2.5.0
  iana_media_type: application/vnd.faf+yaml  # Added (IANA registration)
  created: 2024-06-15  # Preserved
  migrated_from: 2.5.0  # Migration history

# Everything else unchanged
name: my-project
purpose: What it does
version: 1.0.0

architecture:
  type: web-app
  language: TypeScript

stack:
  framework: React 18

Migration time: ~20ms

Examples

Example 1: Migrate from v1.x

User: "Upgrade my FAF format"

Skill Activates:

1. Check current version:

grep -A2 "metadata:" project.faf
# No metadata section found → v1.x format

2. Backup original:

cp project.faf project.faf.backup

3. Migrate:

faf migrate

# Output:
✓ Detected format version: 1.0.0 (legacy)
✓ Backing up to project.faf.backup
✓ Migrating to format version 3.0.0
✓ Adding metadata section
✓ Adding IANA media type
✓ Restructuring architecture section
✓ Migration complete (45ms)

New format version: 3.0.0
IANA compliance: ✓

4. Verify:

faf validate
# ✓ Valid YAML syntax
# ✓ Format version 3.0.0
# ✓ IANA media type: application/vnd.faf+yaml
# ✓ All required fields present
# project.faf is valid!

faf score
# 🥈 Silver (58%) - Same content, modern format

5. Report to user: "Successfully migrated from v1.0.0 to v3.0.0!

Changes:

• Added metadata section
• Added IANA media type (application/vnd.faf+yaml)
• Restructured architecture section
• All original content preserved

Backup: project.faf.backup

Your file is now IANA-compliant and ready to use with all modern FAF tools."

Example 2: Migrate from v2.x

User: "I see a format version warning. How do I update?"

Skill Activates:

1. Check version:

grep "format_version" project.faf
# format_version: 2.3.0

2. Migrate:

faf migrate

# Output:
✓ Detected format version: 2.3.0
✓ Backing up to project.faf.backup
✓ Migrating to format version 3.0.0
✓ Adding IANA media type
✓ Migration complete (18ms)

New format version: 3.0.0

3. Report: "Upgraded from v2.3.0 to v3.0.0 (18ms).

What changed:

• Format version: 2.3.0 → 3.0.0
• Added: IANA media type (application/vnd.faf+yaml)
• Added: Migration history (migrated_from: 2.3.0)

What didn't change:

• All your content (preserved exactly)
• File structure (already modern)
• AI-readiness score (same content)

You're now using the IANA-registered standard."

Example 3: Already on Latest

User: "Migrate my FAF"

Skill Activates:

1. Check version:

grep "format_version" project.faf
# format_version: 3.0.0

2. Run migrate:

faf migrate

# Output:
✓ Already on latest format version: 3.0.0
✓ IANA media type present
✓ No migration needed

project.faf is up to date!

3. Report: "Your project.faf is already on the latest format (v3.0.0). No migration needed!"

Migration Safety

Automatic Backups

Every migration creates a backup:

# Before migration
project.faf  # Original

# After migration
project.faf         # Migrated (new format)
project.faf.backup  # Backup (original, unchanged)

Rollback if needed:

# Restore from backup
cp project.faf.backup project.faf

Content Preservation

Guaranteed preservation:

• ✅ All field values (preserved exactly)
• ✅ All custom sections (preserved)
• ✅ All comments (preserved where possible)
• ✅ All content structure (preserved or improved)

What changes:

• Format version number (old → 3.0.0)
• Metadata structure (adds IANA compliance)
• Section organization (improves, doesn't lose)

What never changes:

• Your project name
• Your project purpose
• Your stack information
• Your testing details
• Your custom content

Validation After Migration

Always validate after migrating:

faf migrate
faf validate  # Should pass with zero errors
faf score     # Should match or improve previous score

If validation fails after migration: This is a bug. Restore backup and report issue:

# Restore original
cp project.faf.backup project.faf

# Report issue at:
# https://github.com/Wolfe-Jam/faf-cli/issues

Troubleshooting

Issue: Migration fails with YAML error

Solution:

# Original file may have syntax errors
faf validate  # Check original FIRST

# Fix syntax errors in original
# Then retry migration
faf migrate

Issue: Backup already exists

Solution:

# Multiple migration attempts create project.faf.backup

# Option 1: Remove old backup
rm project.faf.backup
faf migrate

# Option 2: Save old backup
mv project.faf.backup project.faf.backup.old
faf migrate

Issue: Lost custom sections after migration

Solution:

# This should never happen. Restore and report:
cp project.faf.backup project.faf

# Compare files to identify what was lost
diff project.faf.backup project.faf

# Report issue with diff output

Issue: Score decreased after migration

Solution:

# Migration should not decrease score
# If it does, this is a bug

# Restore backup
cp project.faf.backup project.faf

# Compare scores
faf score  # Original score

# Migrate again with verbose output
faf migrate --verbose  # (if supported)

# Report unexpected score decrease

Supporting Files

This skill works with:

• faf-cli (v5.0.6+) - Migration engine
• project.faf - File being migrated
• project.faf.backup - Safety backup

Related Skills

Migration integrates with:

• faf-validate - Check format before/after migration
• faf-score - Verify score maintained after migration
• faf-init - Alternative: create new file instead of migrating
• faf-sync - Sync migrated file to CLAUDE.md

Key Principles

Zero Data Loss:

• All content preserved
• Automatic backups
• Rollback available
• Safety first

Backward Compatibility:

• Reads all old formats (v1.x, v2.x)
• Upgrades automatically
• No manual intervention required
• Smooth migration path

IANA Compliance:

• Adds official media type
• Updates to registered specification
• Internet standard compliance
• Universal recognition

NO BS ZONE:

• Migration is safe (proven, tested)
• Backups are automatic (not optional)
• Validation is enforced (not skipped)
• Rollback is available (not hidden)

Success Metrics

When this skill succeeds, users should:

1. Have project.faf on format version 3.0.0+
2. Have IANA media type in metadata
3. Have backup of original file
4. Pass validation with zero errors
5. Maintain or improve AI-readiness score
6. Trust the migration process

Quick Reference

Migrate to latest:

faf migrate

Rollback if needed:

cp project.faf.backup project.faf

Verify migration:

faf validate  # Should pass
faf score     # Should match or improve

What gets added:

metadata:
  format_version: 3.0.0  # Updated
  iana_media_type: application/vnd.faf+yaml  # Added
  migrated_from: [old version]  # History

---

Generated by FAF Skill: faf-migrate v1.0.0 Migration Edition: Zero Data Loss "Safe migration. IANA compliance. Championship standards."