@jtf19/vibecoding-kit 0.1.0

package/docs/install-acceptance-checklist.md

@@ -0,0 +1,90 @@
+# Install Acceptance Checklist
+
+本文把 `npm run release:install` 的机器验证补成可人工复现的 installed-project 验收路径。它只验证安装体验，不新增 release-check 命令数，也不改变 install 行为。
+
+## 目标
+
+确认全新业务项目在 Claude、Cursor、Codex 三个平台下都能获得一致的轻量入口、adapter 文档和安全边界提示。
+
+## 准备
+
+从仓库根目录执行。建议使用 `.tmp/` 下的临时目录，避免污染真实业务项目。
+
+如需重跑，先删除对应 `.tmp/manual-install-*` 目录。
+
+## Claude
+
+```bash
+node bin/vibe.mjs init --target .tmp/manual-install-claude --platform claude
+node bin/vibe.mjs doctor --root .tmp/manual-install-claude
+```
+
+人工检查：
+
+- `.tmp/manual-install-claude/CLAUDE.md` 存在。
+- `.tmp/manual-install-claude/AGENTS.md` 不应因单平台 Claude 安装而生成。
+- `.tmp/manual-install-claude/.vibecoding/skills/` 存在。
+- `.tmp/manual-install-claude/.vibecoding/adapters/claude/install.md` 存在。
+- 根入口展示轻量 agent 沙盒入口，并链接 `.vibecoding/VIBE-CODING.md`。
+- `.tmp/manual-install-claude/.vibecoding/VIBE-CODING.md` 包含 `workflow_start.entry_summary` 和 completion summary 相关提示。
+
+## Cursor
+
+```bash
+node bin/vibe.mjs init --target .tmp/manual-install-cursor --platform cursor
+node bin/vibe.mjs doctor --root .tmp/manual-install-cursor
+```
+
+人工检查：
+
+- `.tmp/manual-install-cursor/AGENTS.md` 存在。
+- `.tmp/manual-install-cursor/CLAUDE.md` 不应因单平台 Cursor 安装而生成。
+- `.tmp/manual-install-cursor/.vibecoding/skills/` 存在。
+- `.tmp/manual-install-cursor/.vibecoding/adapters/cursor/install.md` 存在。
+- 根入口展示轻量 agent 沙盒入口，并链接 `.vibecoding/VIBE-CODING.md`。
+- `.tmp/manual-install-cursor/.vibecoding/VIBE-CODING.md` 包含 `workflow_start.entry_summary` 和 completion summary 相关提示。
+
+## Codex
+
+```bash
+node bin/vibe.mjs init --target .tmp/manual-install-codex --platform codex
+node bin/vibe.mjs doctor --root .tmp/manual-install-codex
+```
+
+人工检查：
+
+- `.tmp/manual-install-codex/AGENTS.md` 存在。
+- `.tmp/manual-install-codex/CLAUDE.md` 不应因单平台 Codex 安装而生成。
+- `.tmp/manual-install-codex/.vibecoding/skills/` 存在。
+- `.tmp/manual-install-codex/.vibecoding/adapters/codex/install.md` 存在。
+- 根入口展示轻量 agent 沙盒入口，并链接 `.vibecoding/VIBE-CODING.md`。
+- `.tmp/manual-install-codex/.vibecoding/VIBE-CODING.md` 包含 `workflow_start.entry_summary` 和 completion summary 相关提示。
+
+## 三个平台都必须满足
+
+| 检查点 | 期望 |
+| --- | --- |
+| workflow skills | 位于 `.vibecoding/skills/` |
+| adapter install docs | 位于 `.vibecoding/adapters/<platform>/install.md` |
+| entry summary | 根入口轻量说明，并链接 `.vibecoding/VIBE-CODING.md`；完整规则文档包含 `workflow_start.entry_summary` |
+| completion summary | `.vibecoding/VIBE-CODING.md` 提示先看 `completion_evidence.task_completion_summary` |
+| blocked reasons | 根入口或完整规则提示先看 blocked reasons / readiness gates |
+| session-start bootstrap | 存在 `.vibecoding/hooks/session-start/session-start.mjs` |
+
+## Safety boundary
+
+安装和 session-start bootstrap 必须保持轻量边界：
+
+- 不创建 `.vibecoding-state/`。
+- 不自动运行 runtime、测试或业务命令。
+- 不自动执行 workflow skill。
+- 不调用 subagent、MCP 或平台 API。
+- 不写 git、worktree、commit、push、PR 或 merge。
+
+如果人工验收发现上述边界被破坏，不要把 checklist 改成适配现状；应单独开修复任务，并补充 `release:install` 覆盖。
+
+## 与机器验证的关系
+
+`npm run release:install` 是发布前机器验证；本 checklist 是体验验收补充。
+
+两者的事实源应保持一致：installed-project marker 语义以 `tools/vibe-release-check/release-check-install-suite.mjs` 为准，人工 checklist 只解释如何在真实目录中复现和观察这些 marker。

package/docs/install-claude.md

@@ -0,0 +1,41 @@
+# Claude 安装说明
+
+适合：只需要 Claude 平台差异的用户。完整安装流程见 `docs/install.md`。
+
+## 平台差异
+
+| 项目 | Claude |
+| --- | --- |
+| 根入口 | `CLAUDE.md` |
+| skills 路径 | `.vibecoding/skills/` |
+| adapter 路径 | `.vibecoding/adapters/claude/` |
+| 完整规则 | `.vibecoding/VIBE-CODING.md` |
+
+## 安装
+
+```bash
+node bin/vibe.mjs init --target ../my-project --platform claude
+node bin/vibe.mjs doctor --root ../my-project
+```
+
+安装后，`CLAUDE.md` 只保留轻量 agent 沙盒入口；完整 workflow 规则在 `.vibecoding/VIBE-CODING.md`。
+
+## 验收 Prompt
+
+```text
+帮我确认这个项目的 Vibecoding 入口是否生效。
+```
+
+期望：agent 识别 Vibecoding Kit，按文件路径读取 `.vibecoding/skills/using-vibecoding/SKILL.md` 后做轻量任务分流，不自动执行 workflow skill、不调用 subagent、不触碰 git。
+
+## 如果没有触发
+
+按顺序检查：
+
+- 当前打开的项目目录是否就是 `vibe-init --target` 指向的目录。
+- 目标项目根目录是否存在 `CLAUDE.md`。
+- `CLAUDE.md` 是否提到 `.vibecoding/skills/`、`using-vibecoding` 和 `.vibecoding/VIBE-CODING.md`。
+- `.vibecoding/skills/using-vibecoding/SKILL.md` 是否存在。
+- 如果该文件存在但 agent 仍提示 `using-vibecoding` 缺失，按平台原生 skill registry 未注册处理；应要求 agent 按上述文件路径读取，而不是判定安装失败。
+- `.vibecoding/VIBE-CODING.md` 是否存在。
+- `node bin/vibe.mjs doctor --root ../my-project` 是否输出 `Result: passed`。

package/docs/install-codex.md

@@ -0,0 +1,41 @@
+# Codex 安装说明
+
+适合：只需要 Codex 平台差异的用户。完整安装流程见 `docs/install.md`。
+
+## 平台差异
+
+| 项目 | Codex |
+| --- | --- |
+| 根入口 | `AGENTS.md` |
+| skills 路径 | `.vibecoding/skills/` |
+| adapter 路径 | `.vibecoding/adapters/codex/` |
+| 完整规则 | `.vibecoding/VIBE-CODING.md` |
+
+## 安装
+
+```bash
+node bin/vibe.mjs init --target ../my-project --platform codex
+node bin/vibe.mjs doctor --root ../my-project
+```
+
+安装后，`AGENTS.md` 只保留轻量 agent 沙盒入口；完整 workflow 规则在 `.vibecoding/VIBE-CODING.md`。
+
+## 验收 Prompt
+
+```text
+帮我确认这个项目的 Vibecoding 入口是否生效。
+```
+
+期望：agent 识别 Vibecoding Kit，按文件路径读取 `.vibecoding/skills/using-vibecoding/SKILL.md` 后做轻量任务分流，不自动执行 workflow skill、不调用 subagent、不触碰 git。
+
+## 如果没有触发
+
+按顺序检查：
+
+- 当前打开的项目目录是否就是 `vibe-init --target` 指向的目录。
+- 目标项目根目录是否存在 `AGENTS.md`。
+- `AGENTS.md` 是否提到 `.vibecoding/skills/`、`using-vibecoding` 和 `.vibecoding/VIBE-CODING.md`。
+- `.vibecoding/skills/using-vibecoding/SKILL.md` 是否存在。
+- 如果该文件存在但 agent 仍提示 `using-vibecoding` 缺失，按平台原生 skill registry 未注册处理；应要求 agent 按上述文件路径读取，而不是判定安装失败。
+- `.vibecoding/VIBE-CODING.md` 是否存在。
+- `node bin/vibe.mjs doctor --root ../my-project` 是否输出 `Result: passed`。

package/docs/install-cursor.md

@@ -0,0 +1,41 @@
+# Cursor 安装说明
+
+适合：只需要 Cursor 平台差异的用户。完整安装流程见 `docs/install.md`。
+
+## 平台差异
+
+| 项目 | Cursor |
+| --- | --- |
+| 根入口 | `AGENTS.md` |
+| skills 路径 | `.vibecoding/skills/` |
+| adapter 路径 | `.vibecoding/adapters/cursor/` |
+| 完整规则 | `.vibecoding/VIBE-CODING.md` |
+
+## 安装
+
+```bash
+node bin/vibe.mjs init --target ../my-project --platform cursor
+node bin/vibe.mjs doctor --root ../my-project
+```
+
+安装后，`AGENTS.md` 只保留轻量 agent 沙盒入口；完整 workflow 规则在 `.vibecoding/VIBE-CODING.md`。
+
+## 验收 Prompt
+
+```text
+帮我确认这个项目的 Vibecoding 入口是否生效。
+```
+
+期望：agent 识别 Vibecoding Kit，按文件路径读取 `.vibecoding/skills/using-vibecoding/SKILL.md` 后做轻量任务分流，不自动执行 workflow skill、不调用 subagent、不触碰 git。
+
+## 如果没有触发
+
+按顺序检查：
+
+- 当前打开的项目目录是否就是 `vibe-init --target` 指向的目录。
+- 目标项目根目录是否存在 `AGENTS.md`。
+- `AGENTS.md` 是否提到 `.vibecoding/skills/`、`using-vibecoding` 和 `.vibecoding/VIBE-CODING.md`。
+- `.vibecoding/skills/using-vibecoding/SKILL.md` 是否存在。
+- 如果该文件存在但 agent 仍提示 `using-vibecoding` 缺失，按平台原生 skill registry 未注册处理；应要求 agent 按上述文件路径读取，而不是判定安装失败。
+- `.vibecoding/VIBE-CODING.md` 是否存在。
+- `node bin/vibe.mjs doctor --root ../my-project` 是否输出 `Result: passed`。

package/docs/install-experience-roadmap.md

@@ -0,0 +1,394 @@
+# 安装体验增强路线图
+
+本文档定义 Vibecoding Kit 的安装体验增强 stage。它独立于 runtime roadmap，聚焦项目接入、诊断、升级、修复、卸载和平台 bootstrap。
+
+## 目标定位
+
+当前安装链路已经具备 `vibe-init`、`vibe-doctor`、installed layout、平台 adapter 和轻量交互协议，但仍偏源码仓库工具体验：用户需要在 kit 仓库中运行 `node tools/vibe-init/index.mjs --target <project>`，再手动运行 doctor。
+
+本路线目标是超过 `fork/<external-reference>` 的安装体验：
+
+- 保留平台原生 bootstrap 的低摩擦体验。
+- 增加项目级可审计安装状态：`.vibecoding/`、doctor、managed block、生命周期命令。
+- 默认安全：不覆盖用户入口文件，不默认启用 runtime，不自动创建 `.vibecoding-state/`。
+
+## 生命周期边界
+
+安装体验 lifecycle 和 runtime lifecycle 分离。
+
+```mermaid
+flowchart TD
+  A[Install UX lifecycle] --> B[init]
+  A --> C[doctor]
+  A --> D[update]
+  A --> E[repair]
+  A --> F[uninstall]
+  A --> G[session-start bootstrap]
+
+  H[Runtime lifecycle] --> I[workflow ledger]
+  H --> J[handoff validation]
+  H --> K[dispatch audit]
+  H --> L[execution governance]
+
+  A -. 不写 .vibecoding-state .-> H
+```
+
+安装体验负责：
+
+- 项目接入和平台检测。
+- 入口文件安全合并。
+- `.vibecoding/` 资产安装、升级、修复和卸载。
+- doctor 诊断和发布前 smoke。
+- 轻量 session-start bootstrap。
+- 平台插件与项目安装的职责拆分。
+
+runtime 负责：
+
+- `.vibecoding-state/` workflow ledger。
+- handoff、dispatch、execution、governance 等显式 runtime artifact。
+- default-off 的只读或受控写入 runtime 命令。
+
+## 固定 installed layout
+
+业务项目默认安装结构保持稳定：
+
+```text
+CLAUDE.md          # Claude 入口，按平台生成或合并
+AGENTS.md          # Cursor / Codex 入口，按平台生成或合并
+.vibecoding/
+  skills/
+  adapters/
+  hooks/
+  VIBE-CODING.md
+```
+
+默认不安装：
+
+```text
+.vibecoding-state/
+node_modules/
+平台私有运行目录
+```
+
+`docs/` 和 `examples/` 只有用户显式传入 `--with-docs` 时才安装到 `.vibecoding/`。
+
+## 目标命令形态
+
+当前推荐命令是通过仓库内 wrapper 执行：
+
+```bash
+node bin/vibe.mjs init
+node bin/vibe.mjs init --platform cursor
+node bin/vibe.mjs init --platform all --dry-run
+node bin/vibe.mjs doctor
+node bin/vibe.mjs doctor --root .
+```
+
+后续打包或 link 后的目标形态是：
+
+```bash
+vibe init
+vibe doctor
+vibe update
+vibe repair
+vibe uninstall
+```
+
+当前可执行兼容命令仍是：
+
+```bash
+node tools/vibe-init/index.mjs --target <project> --platform cursor
+node tools/vibe-doctor/index.mjs <project>
+```
+
+## UX-1：路线文档与验收基线
+
+目标：建立安装体验 stage 的事实来源，避免把安装生命周期混入 runtime roadmap。
+
+交付：
+
+- `docs/install-experience-roadmap.md`。
+- `README.md` 快速安装定位更新。
+- `docs/acceptance-checklist.md` 安装体验验收项。
+- `docs/release-guide.md` 安装体验 release smoke 边界。
+
+边界：
+
+- 不改 runtime 实现。
+- 不新增 CLI wrapper。
+- 不改变 installed layout。
+- 不创建 `.vibecoding-state/`。
+
+验收：
+
+- 文档明确区分 install lifecycle 和 runtime lifecycle。
+- acceptance checklist 包含安装体验 smoke 命令。
+- release guide 说明安装体验发布前检查。
+
+## UX-2：CLI 入口产品化
+
+目标：把源码路径命令包装为用户可记忆的 `vibe` 命令。
+
+当前交付：
+
+- `package.json` 定义 `bin.vibe`。
+- `bin/vibe.mjs` 作为薄 wrapper。
+- `init` 复用 `tools/vibe-init/index.mjs`。
+- `doctor` 复用 `tools/vibe-doctor/index.mjs`。
+
+目标命令：
+
+```bash
+node bin/vibe.mjs init
+node bin/vibe.mjs init --platform cursor
+node bin/vibe.mjs init --platform all --dry-run
+node bin/vibe.mjs doctor
+node bin/vibe.mjs doctor --root .
+```
+
+原则：
+
+- CLI wrapper 只做参数路由，不复制 `vibe-init` / `vibe-doctor` 核心逻辑。
+- `node bin/vibe.mjs init` 默认 target 为当前目录。
+- `node bin/vibe.mjs doctor --root <path>` 转换为现有 doctor positional root。
+- 保留 `node tools/...` 兼容调用。
+- 保持无依赖。
+
+验收：
+
+```bash
+node bin/vibe.mjs init --target .tmp/vibe-install-target --platform all --dry-run
+node bin/vibe.mjs doctor --root .tmp/vibe-install-target
+```
+
+## UX-3：Managed Block 安全合并
+
+目标：解决已有 `CLAUDE.md` / `AGENTS.md` 时只能 skip 和手动复制的问题。
+
+目标 block：
+
+```markdown
+<!-- vibecoding:start version=0.2.0 -->
+...
+<!-- vibecoding:end -->
+```
+
+当前策略：
+
+- 无入口文件：创建完整模板，模板自带 managed block。
+- 有入口文件且无 managed block：默认 `manual`，不覆盖用户内容。
+- `--merge=preview` / `--merge-preview`：输出可复制 managed block，不写入。
+- `--merge=append` 或默认模式加 `--yes`：追加 managed block，不删除用户原内容。
+- 有旧 managed block：默认安装或 `--merge=replace` 只替换 block。
+- 有多个或不完整 block：doctor 报告问题，init 不猜测覆盖。
+- 重复运行不重复追加。
+
+验收：
+
+```bash
+node bin/vibe.mjs init --target .tmp/ux3-new --platform cursor
+node bin/vibe.mjs doctor --root .tmp/ux3-new
+node bin/vibe.mjs init --target .tmp/ux3-existing --platform cursor --merge=preview
+node bin/vibe.mjs init --target .tmp/ux3-existing --platform cursor --merge=append
+node bin/vibe.mjs doctor --root .tmp/ux3-existing
+node bin/vibe.mjs init --target .tmp/ux3-existing --platform cursor --merge=append
+```
+
+期望：
+
+- 已有 `AGENTS.md` 不丢用户内容。
+- 重复运行不会重复追加。
+- doctor 能识别 managed block 是否存在和是否过期。
+
+## UX-4：安装配置与生命周期命令
+
+目标：给项目安装状态一个稳定数据源，支撑 update / repair / uninstall。
+
+当前交付：
+
+- `vibe init` 会写入 `.vibecoding/config.json`。
+- `bin/vibe.mjs` 路由 `update` / `repair` / `uninstall` 到 `tools/vibe-lifecycle/index.mjs`。
+- `vibe-doctor` 校验 lifecycle config 的存在、JSON 合法性和 managed entry 状态。
+- `doctor` 输出按 summary-first 呈现，先给 `Health summary`、`Next manual action`，再按 `Blocking`、`Warnings`、`Info` 分组。
+- `update` / `repair` / `uninstall` dry-run 输出包含 `Impact summary`、`Safety boundary`、动作 severity 和下一步人工动作。
+
+当前配置：
+
+```json
+{
+  "version": 1,
+  "profile": "standard",
+  "platforms": ["cursor"],
+  "interaction": "lightweight",
+  "runtime": { "enabled": false },
+  "managed_entries": {
+    "AGENTS.md": true
+  },
+  "docs_installed": false,
+  "lifecycle": {
+    "update": "managed-assets-and-managed-blocks-only",
+    "repair": "missing-assets-and-managed-entries-only",
+    "uninstall": "remove-managed-blocks-and-kit-directory-preserve-runtime-state"
+  }
+}
+```
+
+当前命令：
+
+```bash
+node bin/vibe.mjs update --root <project> --dry-run
+node bin/vibe.mjs repair --root <project> --dry-run
+node bin/vibe.mjs uninstall --root <project> --dry-run
+```
+
+边界：
+
+- `update` 刷新 `.vibecoding/` 资产和已有 managed block。
+- `repair` 补缺失文件，并只在 config 或旧安装状态能证明安全时恢复入口文件。
+- `uninstall` 删除 managed block 和 `.vibecoding/`，保留 `.vibecoding-state/`。
+- 所有命令默认只生成 dry-run plan；写入必须显式传 `--confirm` 或 `--yes`。
+- 没有 managed block 的入口文件永远不被 lifecycle 命令覆盖。
+
+验收：
+
+```bash
+node bin/vibe.mjs init --target .tmp/ux4-config --platform cursor
+node bin/vibe.mjs doctor --root .tmp/ux4-config
+node bin/vibe.mjs repair --root .tmp/ux4-config --dry-run
+node bin/vibe.mjs uninstall --root .tmp/ux4-config --dry-run
+```
+
+期望：
+
+- `doctor` 能识别并校验 `.vibecoding/config.json`，并用 summary-first 输出说明 blocking / warning / info。
+- `repair --dry-run` 能解释将修什么，并显示 `Impact summary`、`Safety boundary` 和 `Next manual action`。
+- `uninstall --dry-run` 能列出删除范围，并明确只删除 managed block / `.vibecoding/`、保留 `.vibecoding-state/`。
+- 不删除用户非 managed 内容。
+
+## UX-5：轻量 session-start bootstrap
+
+目标：补齐新会话自动知道项目安装了 Vibecoding 的体验差距。
+
+当前交付：
+
+- `hooks/session-start/session-start.mjs` 作为跨平台可执行 bootstrap。
+- `hooks/session-start/session-start.md` 收缩为轻量路由提示。
+- Cursor / Codex hook 示例引用安装后的 bootstrap command。
+- Claude adapter 文档说明可用 `--format claude` 输出 SessionStart additional context。
+- adapter `plugin.json` 声明 `sessionStartBootstrap` 能力。
+- doctor 校验 bootstrap 文件、plugin 元数据和 hook 示例引用。
+
+命令：
+
+```bash
+node .vibecoding/hooks/session-start/session-start.mjs --format auto
+node .vibecoding/hooks/session-start/session-start.mjs --format cursor
+node .vibecoding/hooks/session-start/session-start.mjs --format claude
+node .vibecoding/hooks/session-start/session-start.mjs --format codex
+```
+
+原则：
+
+- 只注入轻量 bootstrap，不注入完整长 skill。
+- 提示 agent 先按轻量路由处理，必要时读取 `.vibecoding/skills/using-vibecoding/SKILL.md`。
+- 不调用 runtime，不写 `.vibecoding-state/`，不自动执行 `next_skill`。
+- 不调用 subagent、MCP、daemon、平台 API、git 或 worktree。
+
+验收 prompt：
+
+```text
+我想给这个项目加一个新功能，先帮我规划一下。
+```
+
+期望：
+
+- agent 不直接写代码。
+- agent 识别 Vibecoding 轻量路由。
+- 需求模糊时进入 brainstorming / planning。
+- session-start 输出不包含完整 skill 内容。
+
+## UX-6：平台原生插件打包准备
+
+目标：在 CLI 和项目安装生命周期稳定后，生成平台原生插件草案目录，为 marketplace 发布前 smoke 做准备。
+
+当前交付：
+
+- `tools/vibe-plugin-pack/index.mjs` 从 `adapters/` 生成插件草案。
+- `tools/vibe-plugin-pack/README.md` 说明平台插件和项目安装的职责边界。
+- `bin/vibe.mjs plugin pack` 作为薄 wrapper 路由。
+- repo doctor 检查 UX-6 打包工具存在，并检查工具保留 adapter 事实来源和 runtime state 禁止边界。
+- release check 覆盖 `plugin pack --dry-run`、生成和 `--check`。
+
+生成目录：
+
+```text
+.tmp/vibe-plugins/
+  .cursor-plugin/
+    plugin.json
+    hooks.json
+  .codex-plugin/
+    plugin.json
+    hooks.json
+  .claude-plugin/
+    plugin.json
+    marketplace.json
+    install.md
+```
+
+命令：
+
+```bash
+node bin/vibe.mjs plugin pack --platform all --out .tmp/vibe-plugins --dry-run
+node bin/vibe.mjs plugin pack --platform all --out .tmp/vibe-plugins
+node bin/vibe.mjs plugin pack --platform all --out .tmp/vibe-plugins --check
+```
+
+目标体验：
+
+```text
+Cursor: /add-plugin vibecoding
+Claude: /plugin install vibecoding@...
+Codex: /plugins -> Vibecoding Kit
+```
+
+边界：
+
+- `adapters/` 是事实来源，不常驻手写 `.cursor-plugin/` / `.codex-plugin` / `.claude-plugin` 副本。
+- 默认输出到 `.tmp/`，避免过早 marketplace 化。
+- 平台插件负责会话级 bootstrap。
+- 项目级 `vibe init` 负责 `.vibecoding/` 项目契约。
+- 插件安装不等同于项目安装，二者不互相覆盖。
+- 不复制业务项目状态，不创建 `.vibecoding-state/`。
+
+验收：
+
+- dry-run 能输出三平台生成计划且不写文件。
+- 写入模式能生成三平台插件草案目录。
+- `--check` 能确认生成物与 `adapters/` 中的 manifest / hook 示例一致。
+- 插件草案声明轻量 `sessionStartBootstrap`，且不注入完整 skill、不写 runtime state、不自动执行 `next_skill`。
+- 项目级 `vibe init` 仍能独立安装和 doctor。
+- 平台插件和项目安装职责清楚。
+
+## 推荐实施顺序
+
+1. UX-1：文档和验收先行。
+2. UX-2：CLI wrapper，让命令短起来。
+3. UX-3：managed block，解决真实项目安装痛点。
+4. UX-4：config + update / repair / uninstall，补生命周期。
+5. UX-5：轻量 session-start bootstrap，追平启动体验。
+6. UX-6：平台原生插件打包，最后做分发体验。
+
+## 风险控制
+
+- 过早做 marketplace 会拖慢核心安装体验。
+- session-start 注入过重会增加 token 成本。
+- 没有 managed block 就自动合并入口文件，容易误伤用户规则。
+- 没有 `.vibecoding/config.json` 就做 update / uninstall，只能依赖文件扫描，可靠性不足。
+
+## 本路线不做
+
+- 不默认启用 runtime。
+- 不自动创建 `.vibecoding-state/`。
+- 不自动调用 subagent、MCP、daemon 或平台 API。
+- 不自动改 git、worktree、branch、stash。
+- 不把插件安装等同于项目安装。