用途：为仓库内的依赖族生成升级包，输出到 .agents/plans/upgrade/<topic-slug>/。流程分两阶段：先编写或完善可复用的 family override，再结合实时仓库上下文实例化仓库专属升级包。该工具感知 monorepo，在 enrichment 阶段需锁定明确的 owner surface（仓库根、单一工作区，或仓库根加相关工作区）。生成的包仅为文档/研究产物，生成期间不得实施包变更。
主要能力与工作流：阅读 references/workflow.md 后确定模式（family authoring 或 repo instantiation）。先探测仓库上下文：python3 scripts/detect_repo_context.py --repo-root /path/to/repo --json；再基于锚定包引导清单：python3 scripts/bootstrap_manifest.py --repo-root /path/to/repo --anchor-package lucide-react --out /tmp/upgrade-pack.yaml；用实时探测与上游官方指导丰富清单：python3 scripts/enrich_manifest.py --manifest /tmp/upgrade-pack.yaml；必要时用 $repo-modernizer、$opensrc、$technical-writing、$hard-cut 进一步细化；校验清单 python3 scripts/validate_upgrade_pack.py /tmp/upgrade-pack.yaml；运行只读研究 python3 scripts/research_upgrade_pack.py --manifest /tmp/upgrade-pack.yaml；对 research-bundle.json 中必需官方文档与 API 参考页面执行强制的 web.run 确认，并记录到 web-research-findings.json；重跑只读研究使快照反映已确认页面；运行只读资格验证 python3 scripts/qualify_upgrade_pack.py --manifest /tmp/upgrade-pack.yaml；渲染升级包：python3 scripts/render_upgrade_pack.py --manifest /tmp/upgrade-pack.yaml --output-dir /path/to/repo/.agents/plans/upgrade/<topic>。
输出契约：每个仓库本地包必须正好包含 upgrade-pack.yaml、research-snapshot.json、research-bundle.json、web-research-findings.json、qualification-snapshot.json、<basename>-playbook.md、<basename>-trigger-prompt.md、<basename>-operator-mode.md。清单是规范来源，Markdown 为渲染输出；research-snapshot.json 与 qualification-snapshot.json 是研究、资格阶段的规范机器可读证据，research-bundle.json 是支撑快照的原始证据台账，web-research-findings.json 记录 web.run 对必需官方页面的确认。playbook 是权威人工交接文档，也是实施运行期间唯一可写的包文件；operator-mode 是指回 playbook 的执行差异卡；trigger-prompt 是用于新 Codex 会话的精简启动器。不要手工维护 operator-mode.md 或 trigger-prompt.md，应从清单重新生成。
Family Overrides：编辑任何 override 前先读 references/manifest-schema.md。override 位于 references/family-overrides/，适用于跨仓库复现且需要包级信息的依赖族，涵盖终态决策、研究通道、迁移问题、验证证明、文件命名与 slug 约定。内置 family lanes 包括：lucide-react、nextjs、expo-eas、convex、turborepo、shadcn-radix-ui。override 应保持窄范围，只放族特定信息，通用结构由基础生成器提供。
包管理器与框架探测：按 package.json#packageManager、根 lockfile、仓库文档与 CI 提示的顺序探测目标仓库命令族，并把决定写入 upgrade-pack.yaml，渲染出感知包管理器的命令变量；不得在 pnpm/npm/Yarn 仓库中强行使用 Bun。研究路由使用 references/research-lanes.md 中的默认研究通道；条件路由：仅当 Bun 姿态确实相关时用 $bun-dev，仅当目标仓库检测到框架/插件时才用对应通道，仅当包族影响可见 UI 时才用浏览器通道，除非栅格资产生成确属包族表面，否则不路由 $imagegen。
脚本清单：detect_repo_context.py 检查包管理器、lockfile、文档/CI 提示、框架与包清单；bootstrap_manifest.py 从通用默认值加可选 family override 创建起始清单；enrich_manifest.py 用族特定的仓库探测、当前包版本与实时官方文档快照丰富清单；validate_upgrade_pack.py 在渲染前校验清单契约；research_upgrade_pack.py 收集上游文档、API 参考、发布说明、示例、源码证据、仓库用法映射、包身份、目标版本推理、source-map 漂移检查、来源评分及 web.run 队列，写入 research-snapshot.json 与 research-bundle.json；sync_source_map.py 校验或刷新 references/source-maps/ 下的包 source-map；qualify_upgrade_pack.py 运行族原生只读资格验证并写 qualification-snapshot.json；render_upgrade_pack.py 从规范清单与资格快照渲染仓库本地包。
示例：为已知族 override 引导 python3 scripts/bootstrap_manifest.py --repo-root /path/to/repo --anchor-package lucide-react --out /tmp/lucide-upgrade-pack.yaml；为无 override 的包（如 commander）依次运行 bootstrap、enrich、research、qualify、render（render 输出到 /path/to/repo/.agents/plans/upgrade/commander）；清单细化后可按 enrich、validate、research、qualify、render 的顺序刷新已有仓库本地包。
限制：生成阶段仅产出文档与研究，不实施包变更；研究、资格、渲染等阶段为只读；operator-mode.md 与 trigger-prompt.md 不得手工维护；研究路由与浏览器/图像通道有明确的条件限制；其他未在资料中说明的收费、平台或效果信息暂未提供。