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:

Read docs/blueprint/.manifest.json (v3.0 location) or .claude/blueprints/.manifest.json (v1.x/v2.x location)
If not found in either location, suggest running /blueprint:init instead
Extract current format_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:

Report: "Found deprecated generated commands/skills from /blueprint:generate-commands"
List the files found
Use AskUserQuestion: 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"
If "Yes":
Delete the command files found
Remove entries from manifest.generated.commands
Add to upgrade_history: "Removed deprecated generated commands"
If "Keep": Continue to step 4

If 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:

Read the appropriate migration document from blueprint-migration skill
For v1.x → v2.0: Load migrations/v1.x-to-v2.0.md
For v2.x → v3.0: Load migrations/v2.x-to-v3.0.md
Execute each step with user confirmation for destructive operations

v1.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:

For each skill in manifest.generated_artifacts.skills :
Hash current content
If modified: offer to promote to .claude/skills/ (custom layer)
Otherwise: move to .claude/blueprints/generated/skills/

e. Update manifest to v2.0.0 schema:

Add generated section with content tracking
Add custom_overrides section
Add project.detected_stack field
Bump format_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:

Set has_document_detection: true in manifest
If modular rules enabled, copy document-management-rule.md template to .claude/rules/document-management.md

g. Migrate root documentation (if any found):

Find documentation files in root (excluding standard files)

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:

Analyze each file to determine document type
Move to appropriate docs/ subdirectory
Record migration in upgrade_history

v2.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.

.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:

Change generated.skills to generated.rules
Update all path references from .claude/blueprints/ to docs/blueprint/
Bump 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)
Prompt for next action (use AskUserQuestion):

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:

"Check status" → Run /blueprint:status
"Regenerate rules" → Run /blueprint:generate-rules
"Update CLAUDE.md" → Run /blueprint:claude-md
"Commit changes" → Run /git:commit with migration message

Rollback: If upgrade fails:

Check git status for changes made
Use git checkout -- .claude/ and git checkout -- docs/blueprint/ to restore original structure
Manually move content back if needed
Report specific failure point for debugging

blueprint-upgrade

Safety Notice

Copy this and send it to your AI assistant to learn