blueprint-upgrade

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:

1. 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)

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

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

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

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

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

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

8. 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
   - `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
   

9. 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", "..."]
       }
     ]
   }
   

10. 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)

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