// Versioned migration procedures for blueprint format upgrades (v1.0->v1.1, v1.x->v2.0, v2.x->v3.0, v3.0->v3.1, v3.2->v3.3). Use when /blueprint:upgrade needs version-specific logic, content hashing, safe file moves, or rollback.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | blueprint-migration |
| description | Versioned migration procedures for blueprint format upgrades (v1.0->v1.1, v1.x->v2.0, v2.x->v3.0, v3.0->v3.1, v3.2->v3.3). Use when /blueprint:upgrade needs version-specific logic, content hashing, safe file moves, or rollback. |
| user-invocable | false |
| allowed-tools | Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion, TodoWrite |
| created | "2025-12-22T00:00:00.000Z" |
| modified | "2026-05-09T00:00:00.000Z" |
| reviewed | "2026-04-25T00:00:00.000Z" |
Expert skill for migrating blueprint structures between format versions. This skill is triggered by /blueprint:upgrade and handles version-specific migration logic.
| 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 |
docs/blueprint/manifest.json in v3.0+, or legacy .claude/blueprints/.manifest.json in v1.x/v2.x) for current versiondocs/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..claude/blueprints/.manifest.json — references to this path in v1/v2 migration documents are historical and must not be renamed.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
| 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 |
# 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
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"
When executing migrations:
If migration fails:
| 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)" ] |