/blueprint-upgrade | blueprint-plugin

Upgrade the blueprint structure to the latest format version.

Current Format Version: 3.0.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.0.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.0	3.0.0	Already up to date

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/

(For v2.0 changes when upgrading from v1.x:)
- PRDs, ADRs, PRPs move to docs/ (project documentation)
- Custom overrides in .claude/skills/ and .claude/commands/
- Content hashing for modification detection

Confirm with user (use AskUserQuestion):

question: "Ready to upgrade blueprint from v{current} to v3.0.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.

## Contents

- `.manifest.json` - Blueprint configuration and generated content tracking
- `work-overview.md` - Current work focus and priorities
- `feature-tracker.md` - Feature requirements and status
- `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": {}
  },
  "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
- work-overview.md
- feature-tracker.md
- work-orders/ directory
- ai_docs/ directory

Generated rules (.claude/rules/):
- {n} rules (converted from skills)

Custom layer (.claude/skills/, .claude/commands/):
- {n} promoted rules (preserved modifications)
- {n} promoted commands

[Document detection: enabled (if selected)]

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