@pzy560117/opensuper 0.2.6

package/assets/skills-zh/opensuper-archive/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: opensuper-archive
+description: "OpenSuper 阶段 5：归档。用 /opensuper-archive 调用。同步 delta spec 到主 spec，归档 change。"
+---
+
+# OpenSuper 阶段 5：归档（Archive）
+
+## 前置条件
+
+- 验证已通过（阶段 4 完成）
+- 分支已处理
+- `openspec/changes/<name>/.opensuper.yaml` 中 `verify_result: pass`
+
+## 步骤
+
+### 0. 入口状态验证（Entry Check）
+
+执行入口验证：
+
+```bash
+OPENSUPER_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
+OPENSUPER_STATE="${OPENSUPER_STATE:-$(find "${OPENSUPER_SEARCH_ROOTS[@]}" -path '*/opensuper/scripts/opensuper-state.sh' -type f -print -quit 2>/dev/null)}"
+bash "$OPENSUPER_STATE" check <name> archive
+```
+
+验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
+
+### 1. 执行归档
+
+运行归档脚本，自动完成以下全部步骤：
+
+```bash
+bash "$OPENSUPER_ARCHIVE" "<change-name>"
+```
+
+脚本自动执行：
+1. 入口状态验证（phase=archive, verify_result=pass, archived=false）
+2. Delta spec 同步到主 spec
+3. Design doc 前置元数据标注（archived-with, status）
+4. Plan 前置元数据标注（archived-with）
+5. 移动 change 到归档目录
+6. 通过 `opensuper-state transition <archive-name> archived` 更新 `archived: true`
+
+如脚本返回非零退出码，报告错误并停止。
+如脚本返回零退出码，归档完成。
+脚本摘要中的 `X/Y steps succeeded` 以真实执行步骤计数，不会因 delta spec 同步或文档标注重复累计。
+
+当待同步的 delta spec 与已有主 spec 不一致时，脚本会在覆盖前打印 unified diff 预览，帮助确认归档同步内容。
+
+如需预览而不实际执行，使用 `--dry-run` 参数。
+
+### 2. 生命周期闭环
+
+Spec 生命周期在此完成：
+```
+brainstorming → delta spec → 实施 → 验证 → 主 spec 覆盖 → design doc 标注 → 归档
+```
+
+## 退出条件
+
+- 归档脚本执行成功（退出码 0）
+- 归档目录 `openspec/changes/archive/YYYY-MM-DD-<change-name>/` 存在
+- 归档后的 `.opensuper.yaml` 中 `archived: true`
+
+归档脚本会把 `openspec/changes/<name>/` 移动到 `openspec/changes/archive/YYYY-MM-DD-<name>/`。归档成功后**不要再对原 change 名运行** `bash "$OPENSUPER_GUARD" <change-name> archive`，因为原活跃目录已经不存在。归档完整性以脚本退出码和归档目录状态为准。
+
+## 完成
+
+OpenSuper 流程全部完成。如需开始新工作，调用 `/opensuper` 或 `/opensuper-open`。

package/assets/skills-zh/opensuper-build/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: opensuper-build
+description: "OpenSuper 阶段 3：计划与构建。用 /opensuper-build 调用。制定计划并选择执行方式（subagent 或直接执行）实施。"
+---
+
+# OpenSuper 阶段 3：计划与构建（Build）
+
+## 前置条件
+
+- Design Doc 已创建（阶段 2 完成）
+- 活跃 change 存在
+
+## 步骤
+
+### 0. 入口状态验证（Entry Check）
+
+执行入口验证：
+
+```bash
+OPENSUPER_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
+OPENSUPER_STATE="${OPENSUPER_STATE:-$(find "${OPENSUPER_SEARCH_ROOTS[@]}" -path '*/opensuper/scripts/opensuper-state.sh' -type f -print -quit 2>/dev/null)}"
+OPENSUPER_GUARD="${OPENSUPER_GUARD:-$(find "${OPENSUPER_SEARCH_ROOTS[@]}" -path '*/opensuper/scripts/opensuper-guard.sh' -type f -print -quit 2>/dev/null)}"
+bash "$OPENSUPER_STATE" check <name> build
+```
+
+验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
+
+### 1. 制定计划
+
+**立即执行：** 使用 Skill 工具加载 `superpowers:writing-plans` 技能。禁止跳过此步骤。
+
+技能加载后，按其指引制定计划。计划要求：
+- 保存至 `docs/superpowers/plans/YYYY-MM-DD-<feature>.md`
+- 引用设计文档，拆分为可执行任务
+- **Plan 文件头必须包含关联元数据**：
+
+```yaml
+---
+change: <openspec-change-name>
+design-doc: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
+base-ref: <git rev-parse HEAD before implementation>
+---
+```
+
+`base-ref` 用于验证阶段跨提交统计改动规模。创建计划时先记录当前提交：
+
+```bash
+git rev-parse HEAD
+```
+
+### 2. 更新计划状态
+
+先记录 plan 路径：
+
+```bash
+bash "$OPENSUPER_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
+```
+
+无需手动更新 phase，guard 会在退出条件满足后自动流转。
+
+### 3. 工作区隔离
+
+计划已写入当前分支。在开始执行前，选择工作区隔离方式：
+
+| 选项 | 方式 | 说明 |
+|------|------|------|
+| A | 创建分支 | 在当前仓库创建新分支，简单快速 |
+| B | 创建 Worktree | 隔离工作区，完全独立，适合并行开发 |
+
+**推荐规则**：
+- 变更涉及 ≤ 3 个文件 → 推荐 A
+- 需要并行开发、当前分支有未提交工作 → 推荐 B
+
+用户选择后，更新 `isolation` 字段。`isolation` 只允许以下值之一：
+
+```bash
+bash "$OPENSUPER_STATE" set <name> isolation <value>
+```
+
+- `branch`
+- `worktree`
+
+<IMPORTANT>
+这是脚本级硬约束，不是建议。full workflow 初始化时 `isolation` 可以暂时为 `null`，但只允许存在到本步骤之前。
+进入实现前必须停下来询问用户并写入 `branch` 或 `worktree`。若保持 `null`，`build → verify` 的 guard 和 `opensuper-state transition build-complete` 都会失败。
+</IMPORTANT>
+
+**执行隔离**：
+
+- **branch**：执行 `git checkout -b <change-name>`，后续工作在新分支上进行
+- **worktree**：调用 `superpowers:using-git-worktrees` 技能或使用原生 `EnterWorktree` 工具创建隔离工作区
+
+创建隔离后，确认计划文件可访问（分支方式天然可访问；worktree 方式需确认计划已提交）。
+
+### 4. 选择执行方式
+
+向用户展示计划摘要（任务数、涉及模块），然后询问执行方式：
+
+| 选项 | 技能 | 适用场景 |
+|------|------|---------|
+| A | `superpowers:subagent-driven-development` | 任务独立、复杂度高、需要双阶段审查 |
+| B | `superpowers:executing-plans` | 任务简单、无子agent环境、轻量快速 |
+
+**推荐规则**：
+- 任务数 ≥ 3 → 推荐 A
+- 任务数 ≤ 2 且无跨模块依赖 → 推荐 B
+- 来自 hotfix 路径 → 推荐 B
+
+用户选择后，更新 `build_mode` 字段。`build_mode` 只允许以下值之一：
+
+```bash
+bash "$OPENSUPER_STATE" set <name> build_mode <value>
+```
+
+- `subagent-driven-development`
+- `executing-plans`
+- `direct`（默认仅 hotfix/tweak preset 使用）
+
+full workflow 不得默认使用 `direct`。只有用户明确要求跳过计划执行技能，且你已记录显式 override 时，才允许：
+
+```bash
+bash "$OPENSUPER_STATE" set <name> direct_override true
+bash "$OPENSUPER_STATE" set <name> build_mode direct
+```
+
+没有 `direct_override: true` 时，full workflow 的 `build_mode=direct` 会被 guard 和状态转换同时拦截。
+
+然后，**立即执行：** 使用 Skill 工具加载对应技能。禁止跳过此步骤。
+
+如所选 Superpowers 技能不可用，停止流程并提示安装或启用对应技能，不要用普通对话替代该步骤。
+
+技能加载后，按其指引执行：
+- 按计划执行任务
+- 完成 tasks.md 勾选（`- [ ]` → `- [x]`）
+- 每个任务完成后提交代码
+
+### 5. Spec 增量更新
+
+实施过程中发现初版 spec 不完整时，按变更规模分级处理：
+
+| 规模 | 触发条件 | 做法 |
+|------|---------|------|
+| 小 | 遗漏验收场景、边界条件 | 直接编辑 delta spec + design.md，追加 tasks.md 任务 |
+| 中 | 接口变更、新增组件、数据流变化 | 重新 `superpowers:brainstorming` 更新 Design Doc + delta spec |
+| 大 | 全新 capability 需求 | `/opsx:new` 创建独立 change |
+
+**50% 阈值判定**：以 tasks.md 初始任务总数为基准，若新增任务数超过该总数的一半，视为超出原计划范围，应考虑拆分为新 change。
+
+**原则**：
+- delta spec 是活文档，本阶段期间随时可修改
+- 每次更新应提交，commit message 说明变更原因
+- 不提前同步到 main spec，归档时统一同步
+- 小规模增量直接改 delta spec 时，应在 commit message 中注明，便于归档时判断 design doc 漂移
+
+### 6. 上下文管理
+
+Build 是最长阶段，可能跨越大量任务。为支持上下文压缩后断点恢复：
+
+- **每完成一个 task**：立即勾选 tasks.md 并提交代码，确保 `.opensuper.yaml` 和文件状态持久化
+- **上下文压缩后恢复**：读取 `.opensuper.yaml` 的 `phase` 字段确认仍在 build 阶段，读取 plan 文件头的 `base-ref`，再读取 tasks.md 找到下一个未勾选任务继续执行
+- **长任务拆分**：单任务超过 200 行代码变更时，考虑拆分为多个子任务分别提交
+
+## 退出条件
+
+- tasks.md 全部勾选
+- 代码已提交
+- 已显式运行项目对应的构建/测试命令并通过（不要只依赖 guard 自动猜测）
+- `isolation` 已写为 `branch` 或 `worktree`
+- `build_mode` 已写为 `subagent-driven-development`、`executing-plans` 或带显式 override 的 `direct`
+- **阶段守卫**：运行 `bash "$OPENSUPER_GUARD" <change-name> build --apply`，全部 PASS 后自动流转到 `phase: verify`
+
+Guard 会优先读取项目配置中的命令：
+
+```yaml
+build_command: <build command>
+verify_command: <verify command>
+```
+
+配置位置可为 change 的 `.opensuper.yaml`，也可为仓库根目录的 `.opensuper.yaml` / `opensuper.yaml` / `.opensuper.yml` / `opensuper.yml`。
+未配置时才回退到 `npm run build`、Maven 或 Cargo 的默认探测。构建失败时 guard 会打印失败命令输出，作为排查证据。
+
+退出前运行 guard 自动流转：
+
+```bash
+bash "$OPENSUPER_GUARD" <change-name> build --apply
+```
+
+状态文件自动更新为 `phase: verify`、`verify_result: pending`。
+
+## 自动流转
+
+退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段：
+
+> **REQUIRED NEXT SKILL:** 调用 `opensuper-verify` skill 进入验证与收尾阶段。

package/assets/skills-zh/opensuper-design/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: opensuper-design
+description: "OpenSuper 阶段 2：深度设计。用 /opensuper-design 调用。通过 brainstorming 产出 Design Doc 和 delta spec。"
+---
+
+# OpenSuper 阶段 2：深度设计（Design）
+
+## 前置条件
+
+- 活跃 change 已存在（proposal.md、design.md、tasks.md）
+- 无 Design Doc（`docs/superpowers/specs/` 下无对应文件）
+
+## 步骤
+
+### 0. 入口状态验证（Entry Check）
+
+执行入口验证：
+
+```bash
+OPENSUPER_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
+OPENSUPER_STATE="${OPENSUPER_STATE:-$(find "${OPENSUPER_SEARCH_ROOTS[@]}" -path '*/opensuper/scripts/opensuper-state.sh' -type f -print -quit 2>/dev/null)}"
+OPENSUPER_GUARD="${OPENSUPER_GUARD:-$(find "${OPENSUPER_SEARCH_ROOTS[@]}" -path '*/opensuper/scripts/opensuper-guard.sh' -type f -print -quit 2>/dev/null)}"
+bash "$OPENSUPER_STATE" check <name> design
+```
+
+验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
+
+### 1a. 读取已有上下文
+
+读取活跃 change 下的 `proposal.md` 和 `design.md`，将核心内容整理为摘要：
+- **proposal 摘要**：目标、动机、范围
+- **design 摘要**：架构决策、高层设计
+
+### 1b. 执行 Brainstorming（带上下文）
+
+**立即执行：** 使用 Skill 工具加载 `superpowers:brainstorming` 技能，ARGUMENTS 包含：
+
+```
+Change: <change-name>
+Proposal 摘要: <proposal 核心内容>
+Design 摘要: <design.md 架构决策>
+跳过上下文探索，直接进入设计提问。
+```
+
+禁止跳过此步骤，禁止在未加载该技能的情况下继续。
+
+如 `superpowers:brainstorming` 不可用，停止流程并提示安装或启用 Superpowers 技能，不要用普通对话替代该步骤。
+
+技能加载后，按其指引产出：
+- `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` — 设计文档（技术 RFC）
+- `openspec/changes/<name>/specs/<capability>/spec.md` — 能力规格（delta）
+
+### 2. 更新 OpenSuper 状态
+
+先记录 design_doc 路径，再运行 guard 自动流转：
+
+```bash
+# 记录 design_doc 路径
+bash "$OPENSUPER_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+
+# 自动流转到下一阶段
+bash "$OPENSUPER_GUARD" <change-name> design --apply
+```
+
+状态文件自动更新，无需手动编辑其他字段。
+
+## 退出条件
+
+- Design Doc 已创建并保存
+- 如有新能力则 delta spec 已创建
+- `design_doc` 已写入 `.opensuper.yaml`
+- **阶段守卫**：运行 `bash "$OPENSUPER_GUARD" <change-name> design --apply`，全部 PASS 后自动流转到 `phase: build`
+
+退出前必须使用 `--apply`：
+
+```bash
+bash "$OPENSUPER_GUARD" <change-name> design --apply
+```
+
+## 自动流转
+
+退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段：
+
+> **REQUIRED NEXT SKILL:** 调用 `opensuper-build` skill 进入计划与构建阶段。

package/assets/skills-zh/opensuper-hotfix/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: opensuper-hotfix
+description: "OpenSuper 预设路径：Bug fix / 热修复。跳过 brainstorming，直接 open → build → verify → archive。适用于行为修复、不涉及新 capability 设计的场景。"
+---
+
+# OpenSuper 预设路径：Hotfix
+
+快速 bug fix 工作流：open → build → verify → archive。跳过 brainstorming 和完整 plan，适用于行为修复、不涉及新 capability 设计的场景。
+
+**适用条件**（必须全部满足）：
+1. 修复已有功能的 bug，不新增 capability
+2. 不涉及接口变更或架构调整
+3. 改动范围可预估（通常 ≤ 2 个文件）
+
+**不适用**：如修复过程发现需要架构调整，应升级为完整 `/opensuper` 流程。
+
+---
+
+## 流程（preset workflow，4 阶段）
+
+执行链路：open → build → verify → archive。Hotfix 为每个阶段提供默认决策：精简开启、直接构建、按规模验证、验证通过后归档。
+
+开始前先定位 OpenSuper 脚本：
+
+```bash
+OPENSUPER_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
+OPENSUPER_STATE="${OPENSUPER_STATE:-$(find "${OPENSUPER_SEARCH_ROOTS[@]}" -path '*/opensuper/scripts/opensuper-state.sh' -type f -print -quit 2>/dev/null)}"
+OPENSUPER_GUARD="${OPENSUPER_GUARD:-$(find "${OPENSUPER_SEARCH_ROOTS[@]}" -path '*/opensuper/scripts/opensuper-guard.sh' -type f -print -quit 2>/dev/null)}"
+OPENSUPER_ARCHIVE="${OPENSUPER_ARCHIVE:-$(find "${OPENSUPER_SEARCH_ROOTS[@]}" -path '*/opensuper/scripts/opensuper-archive.sh' -type f -print -quit 2>/dev/null)}"
+```
+
+### 1. 快速开启（preset open）
+
+复用 OpenSuper open 能力创建 change，但使用 hotfix 默认值：不执行 `openspec-explore` 长探索，直接进入精简 change 创建。
+
+**立即执行：** 使用 Skill 工具加载 `openspec-new-change` 技能。禁止跳过此步骤。
+
+技能加载后，按其指引创建精简版产物：
+  - `proposal.md` — 问题描述 + 根因分析 + 修复目标（无需方案对比）
+  - `design.md` — 修复方案（1 个即可，无需多方案对比）
+  - `tasks.md` — 修复任务清单
+- **无需 delta spec**（除非修复改变了已有 spec 的验收场景）
+
+初始化 OpenSuper 状态文件：
+
+```bash
+bash "$OPENSUPER_STATE" init <name> hotfix
+```
+
+初始化后验证状态：
+
+```bash
+bash "$OPENSUPER_STATE" check <name> open
+```
+
+阶段守卫完成 open → build 过渡：
+
+```bash
+bash "$OPENSUPER_GUARD" <change-name> open --apply
+```
+
+### 2. 直接构建（preset build）
+
+使用 hotfix 默认值：`build_mode: direct`。跳过 `superpowers:brainstorming` 和 `superpowers:writing-plans`（除非任务 > 3 个；若超过 3 个任务，转入 `/opensuper-build` 的计划与执行方式选择）。
+
+**立即执行：** 按 tasks.md 逐个执行任务：
+
+1. 读取 `openspec/changes/<name>/tasks.md`，获取未完成任务列表
+2. 对每个未完成任务：
+   - 根据任务描述修改代码
+   - 运行项目格式化命令（如 `mvn spotless:apply`、`npm run format` 等）
+   - 运行相关测试确认通过
+   - 将 tasks.md 中对应 `- [ ]` 勾选为 `- [x]`
+   - 提交代码，commit message 格式：`fix: <简述修复>`
+3. 全部任务完成后，显式运行项目相关测试和构建命令
+4. 运行阶段守卫完成 build → verify 过渡：
+
+```bash
+bash "$OPENSUPER_GUARD" <change-name> build --apply
+```
+
+状态文件自动更新为 `phase: verify`、`verify_result: pending`，然后进入验证。
+
+**如修复影响已有 spec 验收场景**：
+- 在 `openspec/changes/<name>/specs/<capability>/spec.md` 创建 delta spec
+- 仅包含 `## MODIFIED Requirements` 部分
+
+### 3a. Hotfix 专属检查：根因消除
+
+**在加载 opensuper-verify 之前执行**，确保修复确实消除了问题根因：
+
+1. 读取 proposal.md 中的 bug 描述和根因
+2. 搜索验证问题代码不再存在
+3. 如根因未消除，返回 Step 2 继续修复
+
+**升级条件**：
+- 根因消除检查发现深层架构问题 → 停止 hotfix，升级为 `/opensuper`
+- 修复需要额外接口变更 → 停止 hotfix，升级为 `/opensuper`
+
+### 3b. 验证（preset verify）
+
+根因消除检查通过后，复用 `/opensuper-verify`，由 opensuper-verify 的规模评估决定轻量或完整验证。
+
+**立即执行：** 使用 Skill 工具加载 `opensuper-verify` 技能。禁止跳过此步骤。
+
+无 delta spec 的小范围 hotfix 通常满足轻量验证条件（≤ 3 tasks、≤ 2 files），opensuper-verify 的规模评估会选择轻量验证路径（5 项快速检查）。若 hotfix 创建了 delta spec，则根据 opensuper-verify 的规模评估规则进入完整验证路径。
+
+验证通过后，按 `/opensuper-verify` 的规则将 `.opensuper.yaml` 的 `verify_result` 记录为 `pass`，归档前不得跳过该状态。
+
+### 4. 归档（preset archive）
+
+复用 `/opensuper-archive`。归档前必须满足 `.opensuper.yaml` 中 `verify_result: pass`。
+
+**立即执行：** 使用 Skill 工具加载 `opensuper-archive` 技能进行归档。禁止跳过此步骤。
+如有 delta spec，按 opensuper-archive 规则同步到 main spec，并处理关联 Design Doc 与 Plan 的归档标注。
+
+---
+
+## 连续执行模式
+
+<IMPORTANT>
+Hotfix 流程为 **一次性连续执行**。调用 `/opensuper-hotfix` 后，agent 必须自动走完全部 4 个阶段，中间不停顿等待用户输入（除非遇到升级条件需要用户确认）。
+
+执行顺序：快速开启 → 直接构建 → 验证 → 归档 → 完成
+
+每个阶段完成后立即进入下一阶段，无需用户再次输入。阶段内部仍必须按上文要求调用对应 OpenSuper/OpenSpec/Superpowers skill。
+</IMPORTANT>
+
+---
+
+## 升级条件
+
+满足以下**任一**条件时，停止 hotfix 流程，升级为完整 `/opensuper`：
+
+| 条件 | 说明 |
+|------|------|
+| 改动涉及 **3+ 文件** | 超出单点修复范围 |
+| 架构变更 | 新模块、新接口、新依赖 |
+| 数据库 schema 变更 | 结构性调整 |
+| 引入新的 public API | 修复产生了新的对外接口 |
+| 修复范围超出单一函数/模块 | 需要多处协调修改 |
+
+升级方式：在当前 change 基础上补充 Design Doc（执行 `/opensuper-design`），后续正常走完整流程。
+
+---
+
+## 退出条件
+
+- Bug 已修复，测试通过
+- change 已归档
+- 如有 spec 变更，已同步到 main spec
+- **阶段守卫**：build → verify 前运行 `bash "$OPENSUPER_GUARD" <change-name> build --apply`，verify → archive 前按 `/opensuper-verify` 规则运行 `bash "$OPENSUPER_GUARD" <change-name> verify --apply`

package/assets/skills-zh/opensuper-open/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: opensuper-open
+description: "OpenSuper 阶段 1：开启。用 /opensuper-open 调用。通过 OpenSpec 探索想法、创建 change 结构（proposal + design + tasks）。"
+---
+
+# OpenSuper 阶段 1：开启（Open）
+
+## 前置条件
+
+- 无活跃 change，或用户希望创建新 change
+
+## 步骤
+
+### 1. 探索想法
+
+**立即执行：** 使用 Skill 工具加载 `openspec-explore` 技能。禁止跳过此步骤。
+
+技能加载后，按其指引自由探索问题空间。
+
+### 2. 创建 Change 结构 + 初始化状态
+
+**立即执行：** 使用 Skill 工具加载 `openspec-new-change` 技能。若用户意图未明确、需要先形成建议，改为加载 `openspec-propose`。禁止跳过此步骤。
+
+确认以下产物已创建：
+
+```
+openspec/changes/<name>/
+├── .openspec.yaml
+├── .opensuper.yaml
+├── proposal.md       # Why + What：问题、目标、范围
+├── design.md         # How（高层）：架构决策、方案选型
+└── tasks.md          # 任务清单（勾选框）
+```
+
+创建 `.opensuper.yaml` 状态文件：
+
+```bash
+OPENSUPER_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
+OPENSUPER_STATE="${OPENSUPER_STATE:-$(find "${OPENSUPER_SEARCH_ROOTS[@]}" -path '*/opensuper/scripts/opensuper-state.sh' -type f -print -quit 2>/dev/null)}"
+OPENSUPER_GUARD="${OPENSUPER_GUARD:-$(find "${OPENSUPER_SEARCH_ROOTS[@]}" -path '*/opensuper/scripts/opensuper-guard.sh' -type f -print -quit 2>/dev/null)}"
+
+if [ -z "$OPENSUPER_STATE" ] || [ -z "$OPENSUPER_GUARD" ]; then
+  echo "ERROR: OpenSuper scripts not found. Ensure the opensuper skill is installed." >&2
+  return 1
+fi
+
+bash "$OPENSUPER_STATE" init <name> full
+```
+
+### 3. 入口状态验证
+
+验证状态机已正确初始化：
+
+```bash
+bash "$OPENSUPER_STATE" check <name> open
+```
+
+验证通过后继续 Step 4。验证失败时脚本会输出具体失败原因。
+
+### 4. 内容完整性检查
+
+确认三个文档内容完整：
+- **proposal.md**：问题背景、目标、范围、非目标
+- **design.md**：高层架构决策、方案选型、数据流
+- **tasks.md**：任务列表，每个任务有明确描述
+
+## 退出条件
+
+- proposal.md、design.md、tasks.md 均已创建且内容完整
+- **阶段守卫**：运行 `bash "$OPENSUPER_GUARD" <change-name> open --apply`，全部 PASS 后自动流转到下一阶段
+
+退出前必须使用 `--apply`，否则 `.opensuper.yaml` 仍停留在 `phase: open`，下一阶段入口检查会失败。
+
+```bash
+bash "$OPENSUPER_GUARD" <change-name> open --apply
+```
+
+完整流程会自动更新为 `phase: design`；hotfix/tweak preset 会自动更新为 `phase: build`。
+
+## 自动流转
+
+退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段：
+
+> **REQUIRED NEXT SKILL:** 调用 `opensuper-design` skill 进入深度设计阶段。