blueprint-upgrade

What this skill does

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.3.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**:
   ```bash
   # 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.3.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` |
   | 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      | inline (step 3a) |
   | 3.2.x        | 3.3.0      | `migrations/v3.2-to-v3.3.md` |
   | 3.3.0        | 3.3.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[]' "$MANIFEST" 2>/dev/null
   ```

   **If deprecated entries found**:
   - Report: "Found deprecated generated commands/skills from /blueprint:generate-commands"
   - List the files found
   - If `$NONINTERACTIVE` is `true`, skip the prompt and proceed as if "Yes, remove deprecated commands" was chosen.
   - Otherwise, 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' "$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/migrat