blueprint-upgrade

created	"2025-12-17T00:00:00.000Z"
modified	"2026-05-09T00:00:00.000Z"
reviewed	"2026-05-09T00:00:00.000Z"
description	Upgrade blueprint structure to the latest format version. Use when migrating between format versions, enabling monorepo workspaces, or batch upgrading repos.
args	[--non-interactive|-y]
argument-hint	[--non-interactive|-y]
allowed-tools	Read, Write, Edit, Bash, Glob, AskUserQuestion
name	blueprint-upgrade

Upgrade the blueprint structure to the latest format version.

When to Use This Skill

Use this skill when...	Use blueprint-init instead when...
The project has a manifest at v1.x, v2.x, v3.0, v3.1, or v3.2	The project has no docs/blueprint/manifest.json at all
You want the user-facing upgrade entry point with prompts	Use blueprint-migration instead when implementing version-specific logic
You're adding the v3.2 task registry or v3.3 monorepo workspaces	Use blueprint-execute instead when you want auto-detection of next step
You're running batch upgrades across repos with --non-interactive/-y	Use blueprint-status instead to first audit current version

Current Format Version: 3.4.0

This command delegates version-specific migration logic to the blueprint-migration skill.

Parameters

Parse $ARGUMENTS for flags before running any step:

• --non-interactive, --yes, -y: Skip every AskUserQuestion prompt and apply the defaults in the table below. Intended for batch runs across many repos (e.g. looping /blueprint:upgrade -y over FVH repos that are already on main).

Set an internal $NONINTERACTIVE flag to true when any of those tokens appear in $ARGUMENTS; otherwise false. Reference this flag at every AskUserQuestion call site in the steps below.

Non-interactive defaults

When $NONINTERACTIVE is true, use these answers without prompting and record them in upgrade_history[].changes as "auto-selected in non-interactive mode":

Decision point	Step	Default	Rationale
Remove deprecated generated commands	3	"Yes, remove"	Matches "Recommended" option; the files are known-obsolete
Task-registry scheduling mode	3a	"Prompt before running"	Safest; preserves pre-existing behaviour for all tasks
Upgrade confirmation	5	"Yes, upgrade now"	The flag is explicit consent; skip the confirmation gate
Enable document detection (v1.x→v2.0)	7f	"No, keep manual commands only"	Additive feature; do not silently change behaviour in batch mode
Migrate root documentation (v1.x→v2.0)	7g	"No, leave in root"	Least destructive; moving root docs is reversible but surprising
Post-upgrade next action	11	Skip — report and exit	The caller is responsible for follow-up in a batch context

For the v2.x → v3.0 modification-preservation prompt (delegated to migrations/v2.x-to-v3.0.md), default to "Keep modifications" — never discard user-edited content in batch mode, and never "Cancel migration" silently.

If a migration step would require any prompt not listed above, abort the upgrade with a clear message rather than guessing. The caller can re-run interactively for those repos.

Steps:

1. Check current state:

   • Resolve manifest path — check all known locations (in order):
     1. docs/blueprint/.manifest.json (v3.0+ dot-prefixed)
     2. docs/blueprint/manifest.json (v3.1+ without dot prefix)
     3. .claude/blueprints/.manifest.json (v1.x/v2.x location)
   • Store the resolved path as $MANIFEST; if not found in any location, suggest running /blueprint:init instead
   • Extract current format_version (default to "1.0.0" if field missing)

2. Determine upgrade path:

   # Resolve manifest path once — use $MANIFEST in all subsequent jq commands
   if [[ -f docs/blueprint/.manifest.json ]]; then
     MANIFEST=docs/blueprint/.manifest.json
   elif [[ -f docs/blueprint/manifest.json ]]; then
     MANIFEST=docs/blueprint/manifest.json
   elif [[ -f .claude/blueprints/.manifest.json ]]; then
     MANIFEST=.claude/blueprints/.manifest.json
   else
     echo "ERROR: no blueprint manifest found. Run /blueprint:init first."
     exit 1
   fi
   current=$(jq -r '.format_version // "1.0.0"' "$MANIFEST")
   target="3.4.0"
   

   Important: Store the resolved $MANIFEST path. Use it in every jq invocation throughout this skill and in all delegated migration steps. This avoids silent failures when the filename differs from what a command hard-codes.

   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

---

3a. v3.1 → v3.2 migration: Add task registry:

a. Check if task_registry already exists: bash jq -e '.task_registry' "$MANIFEST" 2>/dev/null

  If exists, skip to next step.

b. Ask about maintenance task scheduling:

  If `$NONINTERACTIVE` is `true`, skip the prompt and use "Prompt before running" (no tasks become auto-run).

  Otherwise, 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" 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-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

---

3b. v3.2 → v3.3 migration: Monorepo support:

Delegate to skills/blueprint-migration/migrations/v3.2-to-v3.3.md. Summary of what it does:

a. Classify the blueprint as root, child, or standalone by walking ancestors and descendants for other blueprint manifest files. b. Add a workspaces block to $MANIFEST (omitted for standalone). c. Bump format_version to 3.3.0 and append an entry to upgrade_history. d. For root blueprints, run /blueprint:workspace-scan to populate workspaces.children. e. (Optional) Initialise the root feature-tracker.json workspaces summary for portfolio FR tracking.

All changes are purely additive — standalone projects get no new top-level keys beyond format_version and upgrade_history.

---

3c. v3.3 → v3.4 migration: Automation block (autonomy levels):

Delegate to skills/blueprint-migration/migrations/v3.3-to-v3.4.md. Summary of what it does:

a. Suggest an initial autonomy_level from existing task_registry state (any auto_run: true → suggest level 1; otherwise level 0). Confirm with the user; in $NONINTERACTIVE mode take the suggestion, never higher. b. Add the automation block (autonomy_level, interaction_mode: "normal", work_orders: {auto_draft: false, auto_execute: false}) to $MANIFEST. c. Bump format_version to 3.4.0 and append an entry to upgrade_history.

Purely additive — a missing automation block already behaves as level 0, so the migration changes no behavior until the user raises the level. See ADR-0020 (claude-plugins) for the level model.

4. Display upgrade plan:

   Blueprint Upgrade
   
   Current version: v{current}
   Target version: v3.4.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
   
   Major changes in v3.3:
   - First-class monorepo support: root/child/standalone roles
   - `workspaces` block in manifest.json (additive; standalone projects omit it)
   - New /blueprint:workspace-scan skill for discovering child blueprints
   - Cross-workspace references (`<path>/ADR-NNN`, `/ADR-NNN`)
   - Optional portfolio feature tracking via implemented_by links
   
   Major changes in v3.4:
   - `automation` block: autonomy_level (0 manual / 1 ambient bookkeeping /
     2 quiet autopilot / 3 scheduled pipeline), interaction_mode, work_orders
   - task_registry auto_run/schedule contract becomes executable
     (scripts/blueprint-autorun.sh + SessionStart probe)
   
   (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:

   If $NONINTERACTIVE is true, skip this confirmation and proceed directly to step 6.

   Otherwise, use AskUserQuestion:

   question: "Ready to upgrade blueprint from v{current} to v3.4.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
   • For v3.0 → v3.1: Load migrations/v3.0-to-v3.1.md
   • For v3.1 → v3.2: Execute inline step 3a above
   • For v3.2 → v3.3: Load migrations/v3.2-to-v3.3.md (see step 3b summary)
   • For v3.3 → v3.4: Load migrations/v3.3-to-v3.4.md (see step 3c summary)
   • Execute each step with user confirmation for destructive operations

7. v1.x → v2.0 migration overview (from migration document):

If $NONINTERACTIVE is true, skip this prompt entirely — print the report from step 10 and return. The batch caller owns follow-up (status checks, commits, etc.).

Otherwise, 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

Post-migration assertion: After any version bump, verify format_version actually changed to the target. This catches silent failures where jq operated on the wrong path and exited 0 with empty output:

actual=$(jq -r '.format_version' "$MANIFEST")
if [[ "$actual" != "$target" ]]; then
  echo "ERROR: Migration failed — format_version is '$actual', expected '$target'"
  echo "Check that $MANIFEST was written correctly and rerun the migration step."
  exit 1
fi
echo "Migration verified: format_version = $actual in $MANIFEST"

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