blueprint-upgrade skill

---
model: haiku
created: 2025-12-17
modified: 2026-02-06
reviewed: 2026-01-09
description: "Upgrade blueprint structure to the latest format version"
allowed-tools: Read, Write, Edit, Bash, Glob, AskUserQuestion
name: blueprint-upgrade
---

Upgrade the blueprint structure to the latest format version.

**Current Format Version**: 3.1.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**:
   ```bash
   # 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.1.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.0        | 3.1.0      | Already up to date |

3. **Check for deprecated generated commands**:

   Check for skills generated by the now-deprecated `/blueprint:generate-commands`:

   ```bash
   # 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

---

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/

   (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.1.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**:
      ```bash
      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**:
      ```bash
      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):
      ```bash
      # 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**:
      ```bash
      mkdir -p docs/blueprint/work-orders
      mkdir -p docs/blueprint/ai_docs
      ```

   b. **Move state files from .claude/blueprints/ to docs/blueprint/**:
      ```bash
      # 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/**:
      ```bash
      # 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/**:
      ```bash
      # 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**:
      ```bash
      # 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):
   ```json
   {
     "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", "..."]
       }
     ]
   }
   ```

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)]

   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