Help us improve
Share bugs, ideas, or general feedback.
From blueprint-plugin
Upgrades Claude Code blueprint structure to latest format version 3.2.0 via version-specific migrations, checks manifests, and removes deprecated generated commands.
npx claudepluginhub laurigates/claude-plugins --plugin blueprint-pluginHow this skill is triggered — by the user, by Claude, or both
Slash command
/blueprint-plugin:blueprint-upgradeThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Upgrade the blueprint structure to the latest format version.
Migrates Claude Code blueprint structures between format versions (1.0.x to 3.1.0) via version-specific procedures, manifest updates, content hashing, and user-confirmed file operations.
Maintains blueprint documentation after system modifications to prevent drift. Guides finding, reading, verifying, and updating blueprints using Grep, Read, Write tools.
Upgrades existing workflow scaffolding files (README, mods) to match the current Spacedock version. Detects version stamps, classifies files by upgrade strategy, and guides through five phases.
Share bugs, ideas, or general feedback.
Upgrade the blueprint structure to the latest format version.
Current Format Version: 3.2.0
This command delegates version-specific migration logic to the blueprint-migration skill.
Steps:
Check current state:
docs/blueprint/.manifest.json (v3.0 location) or .claude/blueprints/.manifest.json (v1.x/v2.x location)/blueprint:init insteadformat_version (default to "1.0.0" if field missing)Determine upgrade path:
# Read current version - check both old and new locations
if [[ -f docs/blueprint/.manifest.json ]]; then
current=$(jq -r '.format_version // "3.0.0"' docs/blueprint/.manifest.json)
elif [[ -f .claude/blueprints/.manifest.json ]]; then
current=$(jq -r '.format_version // "1.0.0"' .claude/blueprints/.manifest.json)
fi
target="3.2.0"
Version compatibility matrix:
| From Version | To Version | Migration 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 | migrations/v3.1-to-v3.2.md |
| 3.2.0 | 3.2.0 | Already up to date |
Check for deprecated generated commands:
Check for skills generated by the now-deprecated /blueprint:generate-commands:
# Check for generated project skills (both naming conventions)
ls .claude/skills/project-continue/SKILL.md 2>/dev/null
ls .claude/skills/project-test-loop/SKILL.md 2>/dev/null
# Also check legacy command paths
ls .claude/commands/project-continue.md 2>/dev/null
ls .claude/commands/project/continue.md 2>/dev/null
# Check manifest for generated entries
jq -r '.generated.commands // {} | keys[]' docs/blueprint/.manifest.json 2>/dev/null
If deprecated entries found:
question: "Found deprecated generated commands. These are no longer needed - /blueprint:execute handles workflow orchestration. Remove them?"
options:
- label: "Yes, remove deprecated commands (Recommended)"
description: "Delete generated command files and clean up manifest"
- label: "Keep for now"
description: "Skip removal, continue with upgrade"
manifest.generated.commandsIf no deprecated commands: Continue to step 4
3a. v3.1 → v3.2 migration: Add task registry:
a. Check if task_registry already exists:
bash jq -e '.task_registry' docs/blueprint/manifest.json 2>/dev/null
If exists, skip to next step.
b. Ask about maintenance task scheduling (use AskUserQuestion):
question: "New feature: Task Registry tracks when maintenance tasks last ran. How should tasks be scheduled?" options: - label: "Prompt before running (Recommended)" description: "Always ask before running maintenance tasks" - label: "Auto-run safe tasks" description: "Read-only tasks run automatically when due" - label: "Manual only" description: "Tasks only run when explicitly invoked"
c. Add task_registry to manifest:
Use jq to add the task_registry section to manifest.json with all tasks defaulting to:
- enabled: true (except curate-docs which defaults to false)
- auto_run: based on user choice (safe read-only tasks: adr-validate, feature-tracker-sync, sync-ids)
- last_completed_at: null
- last_result: null
- Default schedules: derive-prd → on-demand, derive-plans → weekly, derive-rules → weekly, generate-rules → on-change, adr-validate → weekly, feature-tracker-sync → daily, sync-ids → on-change, claude-md → on-change, curate-docs → on-demand
- stats: {}
- context: {}
d. Bump format_version to 3.2.0
Display upgrade plan:
Blueprint Upgrade
Current version: v{current}
Target version: v3.0.0
Major changes in v3.0:
- Blueprint state moves from .claude/blueprints/ to docs/blueprint/
- Generated skills become rules in .claude/rules/
- No more generated/ subdirectory - cleaner structure
- All blueprint-related files consolidated under docs/blueprint/
Major changes in v3.2:
- Task registry tracks operational metadata for maintenance tasks
- Smart scheduling: tasks know when they were last run
- Enable/disable individual tasks
- Incremental operations with context persistence
(For v2.0 changes when upgrading from v1.x:)
- PRDs, ADRs, PRPs move to docs/ (project documentation)
- Custom overrides in .claude/skills/
- Content hashing for modification detection
Confirm with user (use AskUserQuestion):
question: "Ready to upgrade blueprint from v{current} to v3.2.0?"
options:
- "Yes, upgrade now" → proceed
- "Show detailed migration steps" → display migration document
- "Create backup first" → run git stash or backup then proceed
- "Cancel" → exit
Load and execute migration document:
blueprint-migration skillmigrations/v1.x-to-v2.0.mdmigrations/v2.x-to-v3.0.mdv1.x → v2.0 migration overview (from migration document):
a. Create docs/ structure:
mkdir -p docs/prds docs/adrs docs/prps
b. Move documentation to docs/:
.claude/blueprints/prds/* → docs/prds/.claude/blueprints/adrs/* → docs/adrs/.claude/blueprints/prps/* → docs/prps/c. Create generated/ structure:
mkdir -p .claude/blueprints/generated/skills
mkdir -p .claude/blueprints/generated/commands
d. Relocate generated content:
manifest.generated_artifacts.skills:
.claude/skills/ (custom layer).claude/blueprints/generated/skills/e. Update manifest to v2.0.0 schema:
generated section with content trackingcustom_overrides sectionproject.detected_stack fieldformat_version to "2.0.0"f. Enable document detection option (new in v2.1):
Use AskUserQuestion:
question: "Would you like to enable automatic document detection? (New feature)"
options:
- label: "Yes - Detect PRD/ADR/PRP opportunities"
description: "Claude will prompt when conversations should become documents"
- label: "No - Keep manual commands only"
description: "Continue using explicit /blueprint: commands"
If enabled:
has_document_detection: true in manifestdocument-management-rule.md template to .claude/rules/document-management.mdg. Migrate root documentation (if any found):
# Find documentation files in root (excluding standard files)
fd -d 1 -e md . | grep -viE '^\./(README|CHANGELOG|CONTRIBUTING|LICENSE|CODE_OF_CONDUCT|SECURITY)'
If documentation files found (e.g., REQUIREMENTS.md, ARCHITECTURE.md, DESIGN.md):
Use AskUserQuestion:
question: "Found documentation files in root: {file_list}. Would you like to migrate them to docs/?"
options:
- label: "Yes, migrate to docs/"
description: "Move to appropriate docs/ subdirectory"
- label: "No, leave in root"
description: "Keep files in current location"
If "Yes" selected:
docs/ subdirectoryv2.x → v3.0 migration overview (from migration document):
a. Create docs/blueprint/ structure:
mkdir -p docs/blueprint/work-orders
mkdir -p docs/blueprint/ai_docs
b. Move state files from .claude/blueprints/ to docs/blueprint/:
# Move manifest
mv .claude/blueprints/.manifest.json docs/blueprint/.manifest.json
# Move work overview if exists
[[ -f .claude/blueprints/work-overview.md ]] && \
mv .claude/blueprints/work-overview.md docs/blueprint/work-overview.md
# Move feature tracker if exists
[[ -f .claude/blueprints/feature-tracker.md ]] && \
mv .claude/blueprints/feature-tracker.md docs/blueprint/feature-tracker.md
# Move work orders if exist
[[ -d .claude/blueprints/work-orders ]] && \
mv .claude/blueprints/work-orders/* docs/blueprint/work-orders/ 2>/dev/null
# Move ai_docs if exist
[[ -d .claude/blueprints/ai_docs ]] && \
mv .claude/blueprints/ai_docs/* docs/blueprint/ai_docs/ 2>/dev/null
c. Move generated skills to .claude/rules/:
# Create rules directory if needed
mkdir -p .claude/rules
# Move each generated skill to rules
for skill in .claude/blueprints/generated/skills/*.md; do
[[ -f "$skill" ]] || continue
name=$(basename "$skill" .md)
mv "$skill" ".claude/rules/${name}.md"
done
d. Copy README template to docs/blueprint/:
# Create docs/blueprint/README.md with overview of blueprint structure
cat > docs/blueprint/README.md << 'EOF'
# Blueprint Documentation
This directory contains the blueprint state and documentation for this project.
## Contents
- `.manifest.json` - Blueprint configuration and generated content tracking
- `feature-tracker.json` - Feature tracking with tasks and progress
- `work-orders/` - Detailed work order documents
- `ai_docs/` - AI-generated documentation
## Related Directories
- `docs/prds/` - Product Requirements Documents
- `docs/adrs/` - Architecture Decision Records
- `docs/prps/` - Problem Resolution Plans
- `.claude/rules/` - Generated rules (from blueprint)
EOF
e. Update manifest to v3.0.0 schema:
generated.skills to generated.rules.claude/blueprints/ to docs/blueprint/format_version to "3.0.0"f. Remove old .claude/blueprints/ directory:
# Verify all content has been moved
if [[ -d .claude/blueprints ]]; then
# Remove empty directories
rm -rf .claude/blueprints/generated
rm -rf .claude/blueprints/work-orders
rm -rf .claude/blueprints/ai_docs
# Remove the blueprints directory if empty
rmdir .claude/blueprints 2>/dev/null || \
echo "Warning: .claude/blueprints/ not empty, manual cleanup may be needed"
fi
Update manifest (v3.0.0 schema):
{
"format_version": "3.0.0",
"created_at": "[preserved]",
"updated_at": "[now]",
"created_by": {
"blueprint_plugin": "3.0.0"
},
"project": {
"name": "[preserved]",
"type": "[preserved]",
"detected_stack": []
},
"structure": {
"has_prds": true,
"has_adrs": "[detected]",
"has_prps": "[detected]",
"has_work_orders": true,
"has_ai_docs": "[detected]",
"has_modular_rules": "[preserved]",
"has_document_detection": "[based on user choice]",
"claude_md_mode": "[preserved]"
},
"generated": {
"rules": {
"[rule-name]": {
"source": "docs/prds/...",
"source_hash": "sha256:...",
"generated_at": "[now]",
"plugin_version": "3.0.0",
"content_hash": "sha256:...",
"status": "current"
}
},
"commands": {}
},
"task_registry": {
"// note": "Added by v3.1 → v3.2 migration step above"
},
"custom_overrides": {
"rules": ["[any promoted rules]"],
"commands": []
},
"upgrade_history": [
{
"from": "{previous}",
"to": "3.0.0",
"date": "[now]",
"changes": ["Moved state to docs/blueprint/", "Converted skills to rules", "..."]
}
]
}
Report:
Blueprint upgraded successfully!
v{previous} → v3.0.0
State files moved to docs/blueprint/:
- .manifest.json
- feature-tracker.json
- work-orders/ directory
- ai_docs/ directory
Generated rules (.claude/rules/):
- {n} rules (converted from skills)
Custom layer (.claude/skills/):
- {n} promoted rules (preserved modifications)
- {n} promoted skills
[Document detection: enabled (if selected)]
Task registry:
- {n} tasks registered with scheduling metadata
- Auto-run mode: {user choice from migration step}
- Run /blueprint:status to see task health dashboard
New v3.0 architecture:
- Blueprint state: docs/blueprint/ (version-controlled with project)
- Generated rules: .claude/rules/ (project-specific context)
- Custom layer: Your overrides, never auto-modified
- Removed: .claude/blueprints/generated/ (no longer needed)
question: "Upgrade complete. What would you like to do next?"
options:
- label: "Check status (Recommended)"
description: "Run /blueprint:status to see updated configuration"
- label: "Regenerate rules from PRDs"
description: "Update generated rules with new tracking"
- label: "Update CLAUDE.md"
description: "Reflect new architecture in project docs"
- label: "Commit changes"
description: "Stage and commit the migration"
Based on selection:
/blueprint:status/blueprint:generate-rules/blueprint:claude-md/git:commit with migration messageRollback: If upgrade fails:
git checkout -- .claude/ and git checkout -- docs/blueprint/ to restore original structure