blueprint-upgrade

将蓝图结构升级到最新格式版本。

当前格式版本：3.3.0

此命令将特定版本的迁移逻辑委托给 blueprint-migration 技能。

参数

运行任何步骤前，先解析 $ARGUMENTS 中的标志：

• --non-interactive、--yes、-y：跳过所有 AskUserQuestion 提示，并采用下表中的默认选项。适用于在多个仓库中批量运行（例如，循环执行 /blueprint:upgrade -y，升级已位于 main 分支上的 FVH 仓库）。

当 $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
   

   如果发现已弃用条目：

   • 报告："Found deprecated generated commands/skills from /blueprint:generate-commands"
   • 列出找到的文件
   • 如果 $NONINTERACTIVE 为 true，则跳过提示，并按已选择“是，删除已弃用命令”继续。
   • 否则，使用 AskUserQuestion：

     question: "发现了已弃用的生成命令。这些命令已不再需要——/blueprint:execute 会处理工作流编排。要删除它们吗？"
     options:
       - label: "是，删除已弃用的命令（推荐）"
         description: "删除生成的命令文件并清理清单"
       - label: "暂时保留"
         description: "跳过删除，继续升级"
     

   • 如果选择“是”：
     • 删除找到的命令文件
     • 从 manifest.generated.commands 中移除条目
     • 将 "Removed deprecated generated commands" 添加到 upgrade_history
   • 如果选择“保留”：继续执行第 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 将 task_registry 部分添加到 "$MANIFEST"，所有任务的默认值如下： - 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 迁移：支持 Monorepo：

委托给 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. 对于根 blueprint，运行 /blueprint:workspace-scan，以填充 workspaces.children。 e. （可选）初始化根 feature-tracker.json 中的 workspaces 汇总，用于组合 FR 跟踪。

所有更改都仅为增量更改——独立项目除 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：
   问题："是否启用自动文档检测？（新功能）"
   选项：
     - 标签："是——检测 PRD/ADR/PRP 机会"
       描述："当对话内容适合整理成文档时，Claude 会提示你"
     - 标签："否——仅保留手动命令"
       描述："继续使用显式的 /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：
   问题："在根目录中找到文档文件：{file_list}。是否要将它们迁移到 docs/？"
   选项：
     - 标签："是，迁移到 docs/"
       描述："移至合适的 docs/ 子目录"
     - 标签："否，保留在根目录"
       描述："将文件保留在当前位置"
   

   如果选择“是”：

   • 分析每个文件以确定文档类型
   • 移至合适的 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
   

   如果存在，则移动功能跟踪文件

   [[ -f .claude/blueprints/feature-tracker.md ]] &&
   mv .claude/blueprints/feature-tracker.md docs/blueprint/feature-tracker.md

   如果存在，则移动工作订单

   [[ -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/**：
   ```bash
   # 如果需要，创建规则目录
   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/：

   # 创建 docs/blueprint/README.md，概述蓝图结构
   cat > docs/blueprint/README.md << 'EOF'
   # 蓝图文档
   
   此目录包含本项目的蓝图状态和文档。
   
   ## 内容
   
   - `.manifest.json` - 蓝图配置和生成内容跟踪信息
   - `feature-tracker.json` - 包含任务和进度的功能跟踪信息
   - `work-orders/` - 详细的工作订单文档
   - `ai_docs/` - AI 生成的文档
   
   ## 相关目录
   
   - `docs/prds/` - 产品需求文档
   - `docs/adrs/` - 架构决策记录
   - `docs/prps/` - 问题解决计划
   - `.claude/rules/` - 生成的规则（来自蓝图）
   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"

根据所选项：

• “检查状态” → 运行 /blueprint:status
• “重新生成规则” → 运行 /blueprint:generate-rules
• “更新 CLAUDE.md” → 运行 /blueprint:claude-md
• “提交更改” → 使用迁移说明运行 /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/ 恢复原始结构
• 如有需要，手动将内容移回
• 报告具体的失败位置以便调试