blueprint-upgrade

ブループリントの構造を最新の形式バージョンにアップグレードします。

現在の形式バージョン：3.3.0

このコマンドは、バージョン固有の移行ロジックをblueprint-migrationスキルに委任します。

パラメーター

手順を実行する前に、$ARGUMENTSを解析してフラグを確認します。

• --non-interactive、--yes、-y：すべてのAskUserQuestionプロンプトをスキップし、以下の表のデフォルトを適用します。すでにmainにあるFVHリポジトリに対して/blueprint:upgrade -yを繰り返し実行するなど、多数のリポジトリを一括処理する場合を想定しています。

$ARGUMENTSにこれらのトークンが含まれている場合は、内部の$NONINTERACTIVEフラグをtrueに設定します。それ以外の場合はfalseに設定します。以下の手順でAskUserQuestionを呼び出す箇所では、毎回このフラグを参照します。

非対話モードでのデフォルト

$NONINTERACTIVEがtrueの場合は、プロンプトを表示せず、以下の回答を使用し、upgrade_history[].changesに「非対話モードで自動選択」と記録します。

判断箇所	手順	デフォルト	理由
非推奨の生成済みコマンドを削除	3	「はい、削除する」	「推奨」オプションに合致し、該当ファイルはすでに不要であることが分かっているため
タスクレジストリのスケジュール設定モード	3a	「実行前に確認する」	最も安全であり、すべてのタスクの既存の動作を維持できるため
アップグレードの確認	5	「はい、今すぐアップグレードする」	フラグによって明示的に同意されているため、確認手順をスキップします
ドキュメント検出を有効化（v1.x→v2.0）	7f	「いいえ、手動コマンドのみを維持する」	機能の追加にあたるため、一括処理モードで動作を暗黙に変更しないようにします
ルートドキュメントを移行（v1.x→v2.0）	7g	「いいえ、ルートに残す」	変更が最小限で済むため。ルートドキュメントの移動は元に戻せますが、予期しない変更になり得ます
アップグレード後の次のアクション	11	スキップ — 結果を報告して終了	一括処理での後続作業は呼び出し元が担当するため

v2.x → v3.0の変更保持に関するプロンプト（migrations/v2.x-to-v3.0.mdに委任）では、デフォルトで**「変更を保持」**を選択します。一括処理モードでユーザーが編集した内容を破棄したり、黙って「移行をキャンセル」したりしてはいけません。

上記に記載されていないプロンプトが必要な移行手順では、推測で進めず、明確なメッセージを表示してアップグレードを中止します。該当するリポジトリは、対話モードで再実行できます。

手順：

1. 現在の状態を確認する：

   • マニフェストのパスを解決します。既知の場所を以下の順にすべて確認します。
     1. docs/blueprint/.manifest.json（v3.0以降、先頭にドットあり）
     2. docs/blueprint/manifest.json（v3.1以降、先頭にドットなし）
     3. .claude/blueprints/.manifest.json（v1.x/v2.xの場所）
   • 解決したパスを$MANIFESTに保存します。どの場所にも見つからない場合は、代わりに/blueprint:initを実行するよう提案します。
   • 現在のformat_versionを抽出します（フィールドがない場合は「1.0.0」をデフォルトにします）。

2. アップグレードパスを決定する：

   # 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"
   

   重要：解決した$MANIFESTのパスを保存します。このスキル内のすべてのjq呼び出しと、委任先のすべての移行手順で使用してください。これにより、コマンドにハードコードされたファイル名が実際のファイル名と異なる場合の、エラーが表面化しない問題を防げます。

   バージョン互換性マトリックス：

   移行元バージョン	移行先バージョン	移行ドキュメント
   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	インライン（手順3a）
   3.2.x	3.3.0	migrations/v3.2-to-v3.3.md
   3.3.0	3.3.0	すでに最新です

3. 非推奨の生成済みコマンドを確認する：

   現在は非推奨の/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[]' "$MANIFEST" 2>/dev/null
   

   非推奨の項目が見つかった場合：

   • 報告：「/blueprint:generate-commands で生成された非推奨のコマンド／スキルが見つかりました」
   • 見つかったファイルを一覧表示します
   • $NONINTERACTIVE が true の場合、確認をスキップし、「はい、非推奨のコマンドを削除する」を選択したものとして続行します。
   • それ以外の場合は、AskUserQuestion を使用します。

     question: "非推奨の生成済みコマンドが見つかりました。これらは不要になりました。/blueprint:execute がワークフローのオーケストレーションを処理します。削除しますか？"
     options:
       - label: "はい、非推奨のコマンドを削除する（推奨）"
         description: "生成されたコマンドファイルを削除し、マニフェストを整理します"
       - label: "今回は保持する"
         description: "削除をスキップして、アップグレードを続行します"
     

   • 「はい」の場合：
     • 見つかったコマンドファイルを削除します
     • manifest.generated.commands から項目を削除します
     • upgrade_history に「Removed deprecated generated commands」を追加します
   • 「保持」の場合：手順 4 に進みます

   非推奨のコマンドがない場合：手順 4 に進みます

---

3a. v3.1 → v3.2 の移行：タスクレジストリの追加：

a. task_registry がすでに存在するか確認します： bash jq -e '.task_registry' "$MANIFEST" 2>/dev/null

  存在する場合は、次の手順に進みます。

b. メンテナンスタスクのスケジュールについて確認します：

  `$NONINTERACTIVE` が `true` の場合、確認をスキップし、「実行前に確認する」を使用します（タスクは自動実行されません）。

  それ以外の場合は、AskUserQuestion を使用します。
  ```
  question: "新機能：タスクレジストリは、メンテナンスタスクが最後に実行された日時を記録します。タスクのスケジュールをどのように設定しますか？"
  options:
    - label: "実行前に確認する（推奨）"
      description: "メンテナンスタスクを実行する前に必ず確認します"
    - label: "安全なタスクを自動実行する"
      description: "読み取り専用のタスクを、実行時期が来たら自動実行します"
    - label: "手動のみ"
      description: "明示的に実行された場合にのみタスクを実行します"
  ```

c. task_registry をマニフェストに追加します： jq を使用して、"$MANIFEST" に task_registry セクションを追加し、すべてのタスクの初期値を次のように設定します。 - enabled: true（ただし、curate-docs の初期値は false） - auto_run：ユーザーの選択に基づいて設定します（安全な読み取り専用タスク：adr-validate、feature-tracker-sync、sync-ids） - last_completed_at: null - last_result: null - デフォルトのスケジュール：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. format_version を 3.2.0 に更新します

---

3b. v3.2 → v3.3 の移行：モノレポ対応：

skills/blueprint-migration/migrations/v3.2-to-v3.3.md に委譲します。実行内容の概要：

a. 他の blueprint マニフェストファイルがないか、祖先および子孫をたどって確認し、blueprint を root、child、standalone に分類します。 b. $MANIFEST に workspaces ブロックを追加します（standalone の場合は省略）。 c. format_version を 3.3.0 に更新し、upgrade_history に項目を追加します。 d. root blueprint の場合は、/blueprint:workspace-scan を実行して workspaces.children に情報を入力します。 e. （任意）ポートフォリオの FR トラッキング用に、root の feature-tracker.json の workspaces サマリーを初期化します。

すべての変更は追加のみです。standalone プロジェクトでは、format_version と upgrade_history 以外の新しいトップレベルキーは追加されません。

4. アップグレード計画を表示します：

   Blueprint Upgrade
   
   Current version: v{current}
   Target version: v3.3.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
   
   (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. ユーザーに確認します：

   $NONINTERACTIVE が true の場合、この確認をスキップして手順 6 に進みます。

   それ以外の場合は、AskUserQuestion を使用します。

   question: "Ready to upgrade blueprint from v{current} to v3.3.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. 移行ドキュメントを読み込んで実行する：

   • blueprint-migration スキルから該当する移行ドキュメントを読み込みます
   • v1.x → v2.0 の場合：migrations/v1.x-to-v2.0.md を読み込みます
   • v2.x → v3.0 の場合：migrations/v2.x-to-v3.0.md を読み込みます
   • v3.0 → v3.1 の場合：migrations/v3.0-to-v3.1.md を読み込みます
   • v3.1 → v3.2 の場合：上記のインライン手順 3a を実行します
   • v3.2 → v3.3 の場合：migrations/v3.2-to-v3.3.md を読み込みます（手順 3b の概要を参照）
   • 破壊的な操作については、ユーザーの確認を得てから各手順を実行します

7. v1.x → v2.0 の移行概要（移行ドキュメントより）：

   a. docs/ 構造を作成する：

   mkdir -p docs/prds docs/adrs docs/prps
   

   b. ドキュメントを docs/ に移動する：

   • .claude/blueprints/prds/* → docs/prds/
   • .claude/blueprints/adrs/* → docs/adrs/
   • .claude/blueprints/prps/* → docs/prps/

   c. generated/ 構造を作成する：

   mkdir -p .claude/blueprints/generated/skills
   mkdir -p .claude/blueprints/generated/commands
   

   d. 生成されたコンテンツを移動する：

   • manifest.generated_artifacts.skills 内の各スキルについて：
     • 現在のコンテンツのハッシュを計算します
     • 変更されている場合：.claude/skills/（カスタムレイヤー）への昇格を提案します
     • それ以外の場合：.claude/blueprints/generated/skills/ に移動します

   e. マニフェストを v2.0.0 スキーマに更新する：

   • コンテンツ追跡用の generated セクションを追加します
   • custom_overrides セクションを追加します
   • project.detected_stack フィールドを追加します
   • format_version を "2.0.0" に更新します

   f. ドキュメント検出オプションを有効にする（v2.1 で追加）：

   $NONINTERACTIVE が true の場合、プロンプトをスキップし、ドキュメント検出を無効のままにします（「いいえ。手動コマンドのみを使用する」として扱います）。

   それ以外の場合：

   AskUserQuestion を使用：
   question: "ドキュメントの自動検出を有効にしますか？（新機能）"
   options:
     - label: "はい。PRD/ADR/PRP の候補を検出する"
       description: "会話をドキュメントにする必要がある場合、Claude が確認します"
     - label: "いいえ。手動コマンドのみを使用する"
       description: "明示的な /blueprint: コマンドを引き続き使用します"
   

   有効にした場合：

   • マニフェストで has_document_detection: true を設定します
   • モジュール式ルールが有効な場合は、document-management-rule.md テンプレートを .claude/rules/document-management.md にコピーします

   g. ルートディレクトリのドキュメントを移行する（見つかった場合）：

   # ルートディレクトリ内のドキュメントファイルを検索する（標準ファイルを除く）
   fd -d 1 -e md . | grep -viE '^\./(README|CHANGELOG|CONTRIBUTING|LICENSE|CODE_OF_CONDUCT|SECURITY)'
   

   ドキュメントファイル（例：REQUIREMENTS.md、ARCHITECTURE.md、DESIGN.md）が見つかった場合：

   $NONINTERACTIVE が true の場合、プロンプトをスキップし、ルートディレクトリのドキュメントはそのままにします（「いいえ。ルートディレクトリに残す」として扱います）。

   それ以外の場合：

   AskUserQuestion を使用：
   question: "ルートディレクトリにドキュメントファイルが見つかりました：{file_list}。docs/ に移行しますか？"
   options:
     - label: "はい。docs/ に移行する"
       description: "適切な docs/ サブディレクトリに移動します"
     - label: "いいえ。ルートディレクトリに残す"
       description: "ファイルを現在の場所に残します"
   

   「はい」を選択した場合：

   • 各ファイルを分析して、ドキュメントの種類を判定します
   • 適切な docs/ サブディレクトリに移動します
   • 移行内容を upgrade_history に記録します

8. v2.x → v3.0 の移行概要（移行ドキュメントより）：

   a. docs/blueprint/ 構造を作成する：

   mkdir -p docs/blueprint/work-orders
   mkdir -p docs/blueprint/ai_docs
   

   b. 状態ファイルを .claude/blueprints/ から docs/blueprint/ に移動する：

   # マニフェストを移動する
   mv .claude/blueprints/.manifest.json docs/blueprint/.manifest.json
   
   # 作業概要が存在する場合は移動する
   [[ -f .claude/blueprints/work-overview.md ]] && \
     mv .claude/blueprints/work-overview.md docs/blueprint/work-overview.md
   # feature tracker が存在する場合は移動
   [[ -f .claude/blueprints/feature-tracker.md ]] && \
     mv .claude/blueprints/feature-tracker.md docs/blueprint/feature-tracker.md
   
   # work orders が存在する場合は移動
   [[ -d .claude/blueprints/work-orders ]] && \
     mv .claude/blueprints/work-orders/* docs/blueprint/work-orders/ 2>/dev/null
   
   # ai_docs が存在する場合は移動
   [[ -d .claude/blueprints/ai_docs ]] && \
     mv .claude/blueprints/ai_docs/* docs/blueprint/ai_docs/ 2>/dev/null
   

   c. 生成されたスキルを .claude/rules/ に移動:

   # 必要に応じて rules ディレクトリを作成
   mkdir -p .claude/rules
   
   # 生成された各スキルを 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. README テンプレートを docs/blueprint/ にコピー:

   # blueprint 構造の概要を記載した docs/blueprint/README.md を作成
   cat > docs/blueprint/README.md << 'EOF'
   # Blueprint ドキュメント
   
   このディレクトリには、このプロジェクトの blueprint の状態とドキュメントが含まれています。
   
   ## 内容
   
   - `.manifest.json` - Blueprint の設定と生成コンテンツの追跡
   - `feature-tracker.json` - タスクと進捗を含む機能の追跡
   - `work-orders/` - 詳細な作業指示書
   - `ai_docs/` - AI が生成したドキュメント
   
   ## 関連ディレクトリ
   
   - `docs/prds/` - 製品要件定義書
   - `docs/adrs/` - アーキテクチャ決定記録
   - `docs/prps/` - 問題解決計画
   - `.claude/rules/` - 生成されたルール（blueprint から）
   EOF
   

   e. マニフェストを v3.0.0 スキーマに更新:

   • generated.skills を generated.rules に変更
   • すべてのパス参照を .claude/blueprints/ から docs/blueprint/ に更新
   • format_version を "3.0.0" に引き上げ

   f. 古い .claude/blueprints/ ディレクトリを削除:

   # すべてのコンテンツが移動済みであることを確認
   if [[ -d .claude/blueprints ]]; then
     # 空のディレクトリを削除
     rm -rf .claude/blueprints/generated
     rm -rf .claude/blueprints/work-orders
     rm -rf .claude/blueprints/ai_docs
     # 空の場合は blueprints ディレクトリを削除
     rmdir .claude/blueprints 2>/dev/null || \
       echo "警告：.claude/blueprints/ は空ではありません。手動でのクリーンアップが必要な場合があります"
   fi
   

9. マニフェストを更新（v3.0.0 スキーマ）：

   {
     "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. 報告：

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. 次のアクションを確認：

$NONINTERACTIVE が true の場合、このプロンプトを完全にスキップし、ステップ 10 のレポートを出力して戻ります。後続の処理（ステータス確認、コミットなど）はバッチ呼び出し元が担当します。

それ以外の場合は、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"

選択に応じた処理：

• "Check status" → /blueprint:status を実行
• "Regenerate rules" → /blueprint:generate-rules を実行
• "Update CLAUDE.md" → /blueprint:claude-md を実行
• "Commit changes" → 移行メッセージを付けて /git:commit を実行

移行後のアサーション： バージョンを引き上げた後は、format_version が実際に目標値に変更されたことを確認します。これにより、jq が誤ったパスを処理し、空の出力で終了コード 0 を返すような、表面化しない失敗を検出できます：

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"

ロールバック： アップグレードに失敗した場合：

• 変更内容を git status で確認します
• git checkout -- .claude/ と git checkout -- docs/blueprint/ を使用して元の構造に戻します
• 必要に応じてコンテンツを手動で元に戻します
• デバッグのため、失敗した箇所を具体的に報告します