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:

Announce step - Explain what will happen
Check prerequisites - Verify source exists, target doesn't
Confirm with user - Use AskUserQuestion for destructive operations
Execute - Perform the migration step
Verify - Check operation succeeded
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)" ]`

blueprint-migration