Versioned migration procedures for upgrading blueprint structure between format versions
Expert skill for migrating blueprint structures between format versions. This skill is triggered by /blueprint:upgrade and handles version-specific migration logic.
.claude/blueprints/.manifest.json for current version1. 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
| 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.2.x | 3.3.0 | migrations/v3.2-to-v3.3.md |
# Read manifest version - check both v3.0 and legacy locations
if [[ -f docs/blueprint/.manifest.json ]]; then
cat docs/blueprint/.manifest.json | jq -r '.format_version'
elif [[ -f .claude/blueprints/.manifest.json ]]; then
cat .claude/blueprints/.manifest.json | jq -r '.format_version'
fi
# Detect v1.0 (no format_version field)
if ! jq -e '.format_version' .claude/blueprints/.manifest.json > /dev/null 2>&1; then
echo "v1.0.0"
fi
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
jq -r '.generated.skills["skill-name"].content_hash' .claude/blueprints/.manifest.json
When executing migrations:
If migration fails:
| Operation | Command |
|---|---|
| Check version | jq -r '.format_version' .claude/blueprints/.manifest.json |
| Hash file | sha256sum file | cut -d' ' -f1 |
| Safe move | cp -r source target && rm -rf source |
| Check empty dir | [ -z "$(ls -A dir)" ] |