MageByte-Zero · Oct 26, 2026 · Oct 26, 2026 · Oct 26, 2026 · Oct 26, 2026
diff --git a/.npmignore b/.npmignore
@@ -1,5 +1,6 @@
 /changes/
 /.superpowers/
 /docs/superpowers/
+/docs/reviews/
 /contest-2026/
 /scripts/sdd-workspace/
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,8 +10,15 @@ The format loosely follows Keep a Changelog.
 
 - Separate legacy recovery instructions from default workflow skills; route existing changes by recorded workflow variant and ship the compatibility reference with the bundled runtime.
 
+### Added
+
+- Add `ssf package-catpaw <new-dir>` to generate one self-contained Skill folder for the current CatPaw (妙手) desktop import flow (#112). The folder carries the matching CLI and nine workflow skills; package relocation and local runtime behavior are verified, while client and cloud acceptance remain pending.
+
 ### Fixed
 
+- Use the operating system's temporary directory for Qoder and shared release installers, including Cursor and ZCODE, fixing Windows installation failures (#134). Reuse WorkBuddy's isolated clone destination and cleanup on failure across all five installer paths, preserving the fix for #89.
+- Register WorkBuddy local installations in `installed_plugins.json` as well as `enabledPlugins`, so the desktop client discovers the installed suite. Preserve other installations and non-user scopes on upgrades, reject damaged registries before replacing the plugin, and carry the CLI version metadata.
+- Include `package.json` with the bundled CLI in shared, Cursor and ZCODE installs so version identification and module metadata stay with the matching skills.
 - Record the change's start commit and branch when `workflow start` enters executing, and resolve the final review range from that anchor, so a repository whose trunk is not named `main`/`master` can record its final review and complete instead of failing with "Final review requires an unambiguous recorded target branch". An isolation context recorded later no longer moves the range origin.
 - Allow a change that entered executing before the start anchor existed to record it once with `ssf state set <change-dir> review_base <start-commit>`. Both anchor fields are write-once: a recorded anchor cannot be overwritten or cleared, so the reviewed range cannot be narrowed through `ssf state set`.
 - Accept a relative `<change-dir>` for every `ssf execution` subcommand. `ssf execution review` previously wrote the report snapshot to the directory the relative path pointed at, then validated it against the change directory's realpath, so the documented `ssf execution review changes/<name> ...` form always failed with an ENOENT on a doubled path.

diff --git a/INSTALL.md b/INSTALL.md
@@ -38,6 +38,7 @@
 | Gemini CLI | `gemini extensions install` | `gemini extensions update` | `gemini extensions uninstall` |
 | OpenCode | plugin entry / skills 目录 | `git pull` | 删除 plugin/skills |
 | WorkBuddy | `ssf install-workbuddy` | 重新运行安装器 | 删除 marketplace 插件并禁用 |
+| CatPaw（妙手，预览） | `ssf package-catpaw <new-dir>` 后在客户端导入 | 重新生成并导入整个文件夹 | 在妙手技能管理中卸载 |
 | CodeBuddy Code CLI | `ssf install-codebuddy` | 重新运行安装器 | `ssf uninstall-codebuddy` |
 | Trae IDE / TRAE Work | `.trae/skills` / 上传 zip 或 .skill / marketplace | `git pull` + 重新导入 | UI 卸载或删除技能目录 |
 | Cline | `ssf install-cline` | 重新运行脚本 | 删除 `.cline/skills/`、`.clinerules/` |
@@ -357,6 +358,8 @@ rm -rf your-project/.agents/skills
 
 WorkBuddy 把 Skill 作为 marketplace 插件管理。安装器把 spec-superflow 部署为单个插件，包含 9 个 skill、运行时依赖（scripts/docs/templates/dist/hooks）、phase-guard 规则和 `.codebuddy-plugin/plugin.json` 清单，写入 `~/.workbuddy/plugins/marketplaces/<marketplace>/plugins/spec-superflow/`。
 
+安装器同时在 `~/.workbuddy/plugins/installed_plugins.json` 登记本地插件的路径与版本，并在 `settings.json` 启用。仅复制文件和写入 `enabledPlugins` 无法让当前桌面客户端识别插件。安装器不修改官方市场清单，也不表示已上架官方市场。
+
 安装器还会分发三份 canonical Markdown command adapter：`/ssf:resume`、`/ssf:switch`、`/ssf:save`。它们仅在 CodeBuddy/WorkBuddy 的 command 机制中提供这些 slash 名称，并调用同一组 CLI guard；不表示所有平台都有完全相同的 slash 命令。
 
 ### 安装（推荐：一键脚本）
@@ -387,21 +390,22 @@ ssf install-workbuddy --dry-run
 ├── rules/phase-guard.md            ← phase-guard 规则（WorkBuddy 自动加载）
 ├── scripts/  docs/  templates/     ← 运行时依赖
 ├── dist/  hooks/
+├── package.json                    ← 同包 CLI 的版本元数据
 ```
 
 `~/.workbuddy/settings.json` 中启用键为 `spec-superflow@cb_teams_marketplace`（单个键，非每 skill 一个）。
 
 ### 升级
 
-重新运行安装命令即可覆盖旧插件并保留已有 `enabledPlugins` 配置。
+重新运行安装命令即可覆盖旧插件，更新安装登记，并保留其他插件的配置与登记。登记文件损坏时会停止安装，保留原插件供排查。
 
 ### 卸载
 
 ```bash
 rm -rf ~/.workbuddy/plugins/marketplaces/cb_teams_marketplace/plugins/spec-superflow
 ```
 
-然后从 `~/.workbuddy/settings.json` 的 `enabledPlugins` 中移除 `spec-superflow@cb_teams_marketplace`。
+然后从 `~/.workbuddy/settings.json` 的 `enabledPlugins` 和 `~/.workbuddy/plugins/installed_plugins.json` 的 `plugins` 中移除 `spec-superflow@cb_teams_marketplace` 的本地安装记录，保留其他插件记录。
 
 ### 验证
 
@@ -415,6 +419,22 @@ cat ~/.workbuddy/plugins/marketplaces/cb_teams_marketplace/plugins/spec-superflo
 
 ---
 
+## CatPaw（妙手，导入包预览）
+
+针对新版妙手工作台，使用[官方支持的本地技能文件夹导入](https://catpaw.meituan.com/docs#/desktop/skills-market)，不写入未经确认的内部目录。此命令随下一版本发布；在当前仓库可先运行：
+
+```bash
+node scripts/spec-superflow.mjs package-catpaw ./catpaw-spec-superflow
+```
+
+输出目录必须不存在。生成的目录包含根 `SKILL.md`、九个流程技能以及同版本 CLI 和所需资源。在妙手「技能」→ 导入本地技能中选择这个文件夹；应用仅需发现根技能 `spec-superflow`，其余流程按需读取包内文件。若选择 ZIP 导入，先压缩完整文件夹，不要只上传 `SKILL.md`。
+
+使用时选择 `spec-superflow` 技能，或明确要求使用 spec-superflow。执行端需要 Node.js 20+ 和 Git。升级时用新版本 CLI 重新生成完整文件夹，再通过妙手导入；不要仅替换技能正文或单独升级全局 `ssf`。
+
+当前已验证生成包移动后仍能运行 CLI、读取参考文档及启动 direct 流程；尚未进行妙手客户端导入和模型调用验收，也未验证云端模式。
+
+---
+
 ## CodeBuddy Code CLI
 
 CodeBuddy Code CLI 直接从 `~/.codebuddy/skills/` 读取 skill，从 `~/.codebuddy/rules/*.md` 自动加载规则（支持 frontmatter 控制是否总是应用），SessionStart hook 从 `~/.codebuddy/settings.json` 的 `hooks` 字段加载（**不是** `~/.codebuddy/hooks/hooks.json`——CodeBuddy 用户级 `hooks.json` 不会被自动加载）。与 WorkBuddy 的 marketplace 插件模型不同，CodeBuddy CLI 把 skill 直接放进共享 `skills/` 目录，与其他 skill 共存；运行时依赖（scripts/docs/templates/dist/hooks）放在独立的 `~/.codebuddy/spec-superflow/` 目录下作为 `${CLAUDE_PLUGIN_ROOT}`。安装器还会把三个 recovery command adapter 重写为调用已部署的本地 runtime（而非固定版本的 `npx` 包），并把 `phase-guard.md` 设为 `alwaysApply: false` 以避免影响普通项目。

diff --git a/README.md b/README.md
@@ -208,7 +208,15 @@ copilot plugin install spec-superflow@spec-superflow
 gemini extensions install https://github.com/MageByte-Zero/spec-superflow
 ```
 
-项目支持 19 个 AI 编程平台。其他平台的安装器、目录和卸载方式见 [INSTALL.md](INSTALL.md)，能力差异见 [平台矩阵](docs/platform-matrix.md)。
+### CatPaw（妙手，导入包预览）
+
+```bash
+node scripts/spec-superflow.mjs package-catpaw ./catpaw-spec-superflow
+```
+
+在妙手「技能」中导入生成的文件夹。包内包含同版本 CLI 和九个流程技能，升级时一起重新导入。此命令随下一版本发布；目前已验证包结构与本地 CLI，尚未完成妙手客户端验收。
+
+项目另支持 19 个 AI 编程平台。其他平台的安装器、目录和卸载方式见 [INSTALL.md](INSTALL.md)，能力差异见 [平台矩阵](docs/platform-matrix.md)。
 
 ## 命令
 
@@ -223,6 +231,7 @@ gemini extensions install https://github.com/MageByte-Zero/spec-superflow
 | `ssf sync <dir>` | 原子同步 delta spec 到发布基线 |
 | `ssf doctor` | 检查安装、版本和资源一致性 |
 | `ssf finish <dir>` | 验证并合并已记录的隔离分支 |
+| `ssf package-catpaw <new-dir>` | 生成妙手可导入的完整技能文件夹 |
 
 运行 `ssf --help` 查看完整命令。`workflow recommend/select/accept`、旧 execution plan 和八状态路由只用于恢复 v1 变更。
 

diff --git a/docs/README_en.md b/docs/README_en.md
@@ -182,7 +182,15 @@ copilot plugin install spec-superflow@spec-superflow
 gemini extensions install https://github.com/MageByte-Zero/spec-superflow
 ```
 
-The project supports 19 AI coding platforms. See [INSTALL.md](../INSTALL.md) for every installer and uninstall path, and the [platform matrix](platform-matrix.md) for capability differences.
+### CatPaw (妙手, import preview)
+
+```bash
+node scripts/spec-superflow.mjs package-catpaw ./catpaw-spec-superflow
+```
+
+Import the generated folder from CatPaw's Skills page. It contains the matching CLI and all nine workflow skills; reimport the whole folder when upgrading. This command is planned for the next release. Package structure and local CLI behavior have been tested; CatPaw client acceptance is pending.
+
+The project also supports 19 AI coding platforms. See [INSTALL.md](../INSTALL.md) for every installer and uninstall path, and the [platform matrix](platform-matrix.md) for capability differences.
 
 ## Commands
 
@@ -197,6 +205,7 @@ The project supports 19 AI coding platforms. See [INSTALL.md](../INSTALL.md) for
 | `ssf sync <dir>` | Atomically publish delta specs to the baseline |
 | `ssf doctor` | Check installation, versions, and assets |
 | `ssf finish <dir>` | Verify and merge recorded isolation |
+| `ssf package-catpaw <new-dir>` | Create a complete Skill folder for CatPaw import |
 
 Run `ssf --help` for the full command list. `workflow recommend/select/accept`, legacy execution plans, and the eight-state router remain only for v1 recovery.
 

diff --git a/docs/platform-matrix.md b/docs/platform-matrix.md
@@ -34,6 +34,8 @@ spec-superflow 共支持 **19 个** AI 编程平台。每个平台按三层接
 
 Codex manifest 通过 `"hooks": {}` 抑制 `hooks/hooks.json` 自动发现，因此 CLI / App 只加载 skills，不会自动注入 SessionStart 上下文；新会话需显式调用 `workflow-start`。
 
+另提供新版 CatPaw（妙手）的导入包预览：`ssf package-catpaw <new-dir>` 生成包含同版本 CLI 和九个流程技能的单一 Skill 文件夹，通过客户端导入。已验证本地包与 CLI，妙手客户端和云端模式尚未验收，因此暂不计入上表的完整平台支持。
+
 ## 路径来源
 
 所有 `skillsDir` / `rulesDir` / `rulesFormat` / `hookFormat` 均与 [comet](https://github.com/rpamis/comet) 的 `src/core/platforms.ts` 交叉核实，并对照各平台官方约定。spec-superflow 的守卫机制是 **phase-guard 规则文件**（平台自动加载），而非 comet 的 PreToolUse 钩子——这是两层架构的根本区别。

diff --git a/docs/release-checklist.md b/docs/release-checklist.md
@@ -11,14 +11,14 @@ Use this checklist before publishing a new version of `spec-superflow`.
 - `LICENSE` is present
 - `ssf version <semver>` covers all manifests (JSON) + documentation (Markdown/shell)
 - `node scripts/check-version-consistency.mjs` passes (also runs in CI)
-- Verify all nine runtime-dependent canonical skills use the exact release version, and local installer output rewrites them to its bundled `scripts/spec-superflow.mjs`.
+- Verify all nine runtime-dependent canonical skills invoke the CLI bundled with the same release, and local installer output binds them to its bundled `scripts/spec-superflow.mjs`; do not add independent npm version pins to source skills.
 - Verify `.github/plugin/marketplace.json` and `.claude-plugin/marketplace.json` versions match
 
 ## Workflow Integrity
 
 - skill descriptions still match their actual responsibilities
 - `workflow-start` still acts as the primary entry point
-- `contract-builder` still requires explicit approval before execution
+- `contract-builder` remains limited to legacy changes and retains their recorded approval obligations; new direct/planned changes do not create a handwritten execution contract.
 - planning artifacts and execution contract roles remain distinct
 - self-contained ownership is preserved
 
@@ -32,7 +32,7 @@ Use this checklist before publishing a new version of `spec-superflow`.
 
 ## Example Quality
 
-For each example in `docs/examples/`:
+Validate examples according to their recorded workflow variant. Existing legacy fixtures in `docs/examples/` retain the following artifacts; new planned examples require proposal.md + tasks.md, with specs/design only when needed:
 
 - `README.md` explains the scenario
 - `proposal.md` defines intent and scope