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)

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

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

安装

Read current version - check both old and new locations

Check for generated project skills (both naming conventions)

Also check legacy command paths

Check manifest for generated entries

Find documentation files in root (excluding standard files)

Move manifest

Move work overview if exists

Move feature tracker if exists

Move work orders if exist

Move ai_docs if exist

Create rules directory if needed

Move each generated skill to rules

Create docs/blueprint/README.md with overview of blueprint structure

Blueprint Documentation

Contents

Verify all content has been moved

Remove empty directories

Remove the blueprints directory if empty

安装

Read current version - check both old and new locations

Check for generated project skills (both naming conventions)

Also check legacy command paths

Check manifest for generated entries

Find documentation files in root (excluding standard files)

Move manifest

Move work overview if exists

Move feature tracker if exists

Move work orders if exist

Move ai_docs if exist

Create rules directory if needed

Move each generated skill to rules

Create docs/blueprint/README.md with overview of blueprint structure

Blueprint Documentation

Contents

Related Directories

Verify all content has been moved

Remove empty directories

Remove the blueprints directory if empty