laurigates/blueprint-migration

Blueprint Migration

Expert skill for migrating blueprint structures between format versions. This skill is triggered by /blueprint:upgrade and handles version-specific migration logic.

When to Use This Skill

| Use this skill when... | Use blueprint-upgrade instead when... | |---|---| | You need version-specific migration logic (v3.0→v3.1, v3.2→v3.3, etc.) | You're invoking the user-facing upgrade workflow with prompts | | You need content hashing to detect manual modifications during migration | You want the high-level "upgrade my blueprint" entry point | | You're implementing a new migration step between format versions | Use blueprint-init instead when the project has no manifest yet |

Core Expertise

• Reading and parsing the blueprint manifest (docs/blueprint/manifest.json in v3.0+, or legacy .claude/blueprints/.manifest.json in v1.x/v2.x) for current version
• Determining appropriate migration path based on version comparison
• Executing versioned migration steps with user confirmation
• Content hashing for detecting manual modifications
• Safe file moves with rollback capability

Canonical Manifest Filename

• v3.0+: docs/blueprint/manifest.json (canonical, no dot prefix — produced by /blueprint:init). Some repos carry a legacy docs/blueprint/.manifest.json from earlier v3.0 migrations; upgrade tooling tolerates both via the $MANIFEST variable resolved in /blueprint:upgrade Step 2.
• v1.x/v2.x (historical): .claude/blueprints/.manifest.json — references to this path in v1/v2 migration documents are historical and must not be renamed.

Migration Workflow

1. Read current manifest version
2. Compare with target version (latest: 3.3.0)
3. Load migration document for version range
4. Execute migration steps sequentially
5. Confirm each destructive operation
6. Update manifest to target version
7. Report migration summary

Available Migrations

| From | To | Document | |------|-----|----------| | 1.0.x | 1.1.x | migrations/v1.0-to-v1.1.md | | 1.x.x | 2.0.0 | migrations/v1.x-to-v2.0.md | | 2.x.x | 3.0.0 | migrations/v2.x-to-v3.0.md | | 3.0.x | 3.1.0 | migrations/v3.0-to-v3.1.md | | 3.1.x | 3.2.0 | inline in blueprint-upgrade (step 3a) | | 3.2.x | 3.3.0 | migrations/v3.2-to-v3.3.md |

Version Detection

# Resolve manifest path — canonical first, then tolerated variants
if [[ -f docs/blueprint/manifest.json ]]; then
  MANIFEST=docs/blueprint/manifest.json
elif [[ -f docs/blueprint/.manifest.json ]]; then
  MANIFEST=docs/blueprint/.manifest.json
elif [[ -f .claude/blueprints/.manifest.json ]]; then
  MANIFEST=.claude/blueprints/.manifest.json
fi

jq -r '.format_version // "1.0.0"' "$MANIFEST"

# Detect v1.0 (no format_version field — legacy v1.x/v2.x location only)
if [[ -f .claude/blueprints/.manifest.json ]] && \
   ! jq -e '.format_version' .claude/blueprints/.manifest.json > /dev/null 2>&1; then
  echo "v1.0.0"
fi

Content Hashing

For detecting modifications to generated content:

# Generate SHA256 hash of file content
sha256sum path/to/file | cut -d' ' -f1

# Compare with stored hash in manifest (use $MANIFEST from Version Detection above)
jq -r '.generated.skills["skill-name"].content_hash' "$MANIFEST"

Migration Execution Pattern

When executing migrations:

1. Announce step - Explain what will happen
2. Check prerequisites - Verify source exists, target doesn't
3. Confirm with user - Use AskUserQuestion for destructive operations
4. Execute - Perform the migration step
5. Verify - Check operation succeeded
6. Update manifest - Track completion in manifest

Error Handling

If migration fails:

• Stop immediately (fail-fast)
• Report which step failed and why
• Preserve original files (don't delete until confirmed)
• Provide manual recovery instructions

Quick Reference

| Operation | Command | |-----------|---------| | Check version | jq -r '.format_version' "$MANIFEST" (resolve $MANIFEST first; see Version Detection) | | Hash file | sha256sum file \| cut -d' ' -f1 | | Safe move | cp -r source target && rm -rf source | | Check empty dir | [ -z "$(ls -A dir)" ] |