@pzy560117/opensuper 0.2.6

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

@@ -0,0 +1,82 @@
+---
+name: opensuper-open
+description: "OpenSuper Phase 1: Open. Invoke with /opensuper-open. Explore ideas through OpenSpec and create change structure (proposal + design + tasks)."
+---
+
+# OpenSuper Phase 1: Open
+
+## Prerequisites
+
+- No active change, or user wishes to create a new change
+
+## Steps
+
+### 0. Locate OpenSuper Scripts
+
+Locate scripts before creating state:
+
+```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
+```
+
+### 1. Explore Idea
+
+**Immediately execute:** Use the Skill tool to load the `openspec-explore` skill. Skipping this step is prohibited.
+
+After the skill loads, freely explore the problem space following its guidance.
+
+### 2. Create Change Structure
+
+**Immediately execute:** Use the Skill tool to load the `openspec-new-change` skill. If user intent is unclear and needs to form a proposal first, load `openspec-propose` instead. Skipping this step is prohibited.
+
+Confirm the following artifacts have been created:
+
+```
+openspec/changes/<name>/
+├── .openspec.yaml
+├── .opensuper.yaml
+├── proposal.md       # Why + What: problem, goals, scope
+├── design.md         # How (high-level): architectural decisions, solution selection
+└── tasks.md          # Task checklist (checkboxes)
+```
+
+### 3. Initialize OpenSuper State
+
+Initialize OpenSuper state file:
+
+```bash
+bash "$OPENSUPER_STATE" init <name> full
+```
+
+### 4. Content Completeness Check
+
+Confirm the three documents have complete content:
+- **proposal.md**: problem background, goals, scope, non-goals
+- **design.md**: high-level architectural decisions, solution selection, data flow
+- **tasks.md**: task list, each task has a clear description
+
+## Exit Conditions
+
+- proposal.md, design.md, and tasks.md are all created with complete content
+- **Phase guard**: Run `bash "$OPENSUPER_GUARD" <change-name> open --apply`; after all PASS, state automatically advances to the next phase
+
+You must use `--apply` before exiting. Otherwise `.opensuper.yaml` stays at `phase: open`, and the next phase entry check will fail.
+
+```bash
+bash "$OPENSUPER_GUARD" <change-name> open --apply
+```
+
+Full workflow advances to `phase: design`; hotfix/tweak presets advance to `phase: build`.
+
+## Automatic Transition
+
+After exit conditions are met, **proceed immediately to the next phase without waiting for user input**:
+
+> **REQUIRED NEXT SKILL:** Invoke `opensuper-design` skill to enter the deep design phase.

package/assets/skills/opensuper-tweak/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: opensuper-tweak
+description: "OpenSuper preset path: Non-bug small changes (tweak). Skip brainstorming and full plan, directly open → lightweight build → light verify → archive. Applicable for copy, configuration, documentation or prompt local optimization."
+---
+
+# OpenSuper Preset Path: Tweak
+
+Tweak is a preset workflow of OpenSuper's five-phase capabilities, not a separate parallel process. It reuses open, build, verify, archive capabilities, only skipping brainstorming and full plan.
+
+Applicable for small-scale non-bug changes, such as copy adjustments, configuration adjustments, documentation or prompt local optimization.
+
+**Applicable conditions** (all must be met):
+1. No new capability
+2. No architecture changes
+3. No interface changes involved
+4. Usually not exceeding 3 tasks, 4 files
+
+**Not applicable**: If change process discovers need for capability, architecture, or interface adjustments, should upgrade to full `/opensuper` workflow.
+
+---
+
+## Process (preset workflow, 4 phases)
+
+Execution chain: open → lightweight build → light verify → archive. Tweak provides default decisions for each phase: streamlined open, lightweight build, lightweight verification, archive after verification passes.
+
+Locate OpenSuper scripts before starting:
+
+```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. Quick Open (preset open)
+
+Reuse OpenSuper open capability to create change, but use tweak defaults: do not execute `openspec-explore` long exploration, directly enter streamlined change creation.
+
+**Immediately execute:** Use the Skill tool to load the `openspec-new-change` skill. Skipping this step is prohibited.
+
+After the skill loads, follow its guidance to create streamlined artifacts:
+  - `proposal.md` — change motivation + goals + scope
+  - `design.md` — brief implementation description (no solution comparison needed)
+  - `tasks.md` — not exceeding 3 tasks
+- **No delta spec needed** (unless change changes existing spec acceptance scenarios; once delta spec needed, upgrade to full `/opensuper`)
+
+Initialize OpenSuper state file:
+
+```bash
+bash "$OPENSUPER_STATE" init <name> tweak
+```
+
+Run phase guard to transition open → build:
+
+```bash
+bash "$OPENSUPER_GUARD" <change-name> open --apply
+```
+
+### 2. Lightweight Build (preset build)
+
+Use tweak defaults: `build_mode: direct`. Skip `superpowers:brainstorming` and `superpowers:writing-plans`.
+
+**Immediately execute:** Execute tasks one by one according to tasks.md:
+
+1. Read `openspec/changes/<name>/tasks.md`, get incomplete task list
+2. For each incomplete task:
+   - Modify target file according to task description
+   - Run project formatter (e.g., `mvn spotless:apply`, `npm run format`)
+   - Run related tests to confirm pass
+   - Check corresponding `- [ ]` to `- [x]` in tasks.md
+   - Commit code, commit message format: `tweak: <brief change description>`
+3. After all tasks complete, explicitly run relevant project tests and build commands
+4. Run phase guard to transition build → verify:
+
+```bash
+bash "$OPENSUPER_GUARD" <change-name> build --apply
+```
+
+State automatically updates to `phase: verify`, `verify_result: pending`, then enter verification.
+
+### 3. Lightweight Verification (preset verify)
+
+Reuse `/opensuper-verify`. Tweak must maintain lightweight verification conditions: ≤ 3 tasks, ≤ 4 files, no delta spec, no new capability.
+
+**Immediately execute:** Use the Skill tool to load the `opensuper-verify` skill. Skipping this step is prohibited.
+
+If scale assessment enters full verification path, stop tweak, upgrade to full `/opensuper`.
+
+After verification passes, record `.opensuper.yaml` `verify_result` as `pass` according to `/opensuper-verify` rules, must not skip this status before archiving.
+
+### 4. Archive (preset archive)
+
+Reuse `/opensuper-archive`. Must satisfy `verify_result: pass` in `.opensuper.yaml` before archiving.
+
+**Immediately execute:** Use the Skill tool to load the `opensuper-archive` skill to archive. Skipping this step is prohibited.
+
+---
+
+## Continuous Execution Mode
+
+<IMPORTANT>
+Tweak workflow is **one-time continuous execution**. After invoking `/opensuper-tweak`, agent must automatically complete all 4 phases, without pausing to wait for user input mid-way (unless encountering upgrade conditions requiring user confirmation).
+
+Execution order: quick open → lightweight build → lightweight verification → archive → complete
+
+After each phase completes, immediately enter next phase, no need for user input again. Within each phase, must still call corresponding OpenSuper/OpenSpec/Superpowers skill according to above requirements.
+</IMPORTANT>
+
+---
+
+## Upgrade Conditions
+
+Upgrade to full `/opensuper` when **any** of the following conditions are met:
+
+| Condition | Explanation |
+|-----------|-------------|
+| Change involves **5+ files** | Exceeds small change scope |
+| Cross-module coordination required | Needs coordination across components |
+| **5+** new test cases needed | Change complexity increasing |
+| Config item additions or deletions | Non-value config changes |
+| New capability needed | Exceeds local optimization |
+| Delta spec needed | Affects existing specifications |
+
+Upgrade method: On current change basis, supplement Design Doc (execute `/opensuper-design`), then proceed normally with full workflow.
+
+---
+
+## Exit Conditions
+
+- Small change completed, tests pass
+- Change archived
+- No new capability, architecture adjustments, or interface changes
+- **Phase guard**: Before build → verify run `bash "$OPENSUPER_GUARD" <change-name> build --apply`; before verify → archive follow `/opensuper-verify` and run `bash "$OPENSUPER_GUARD" <change-name> verify --apply`

package/assets/skills/opensuper-verify/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: opensuper-verify
+description: "OpenSuper Phase 4: Verify and Complete. Invoke with /opensuper-verify. Verify implementation matches design, handle development branch."
+---
+
+# OpenSuper Phase 4: Verify and Complete (Verify)
+
+## Prerequisites
+
+- Code has been committed (Phase 3 complete)
+- All tasks in tasks.md are complete
+
+## Steps
+
+### 0. Entry State Verification (Entry Check)
+
+Execute entry verification:
+
+```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> verify
+```
+
+Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
+
+### 1. Change Scale Assessment
+
+Execute scale assessment:
+
+```bash
+bash "$OPENSUPER_STATE" scale <name>
+```
+
+Script automatically counts tasks, delta specs, and changed files to determine whether to use light or full verification mode, and sets the verify_mode field.
+
+Note: if the build phase committed after each task, worktree diff can underestimate change size. In that case, read the plan header `base-ref` and re-check the full commit range:
+
+```bash
+PLAN=$(bash "$OPENSUPER_STATE" get <name> plan)
+BASE_REF=$(grep '^base-ref:' "$PLAN" 2>/dev/null | head -1 | sed 's/^base-ref: *//')
+git diff --stat "$BASE_REF"...HEAD
+```
+
+If the commit range exceeds lightweight thresholds (> 5 files, cross-module coordination, or more than 1 delta spec capability), manually switch to full verification:
+
+```bash
+bash "$OPENSUPER_STATE" set <name> verify_mode full
+```
+
+### 2a. Lightweight Verification (Small Changes)
+
+When scale assessment result is "small", skip `openspec-verify-change`, directly execute the following checks:
+
+1. All tasks in tasks.md completed `[x]`
+2. Changed files consistent with tasks.md description (compare `git diff --stat` against task content)
+3. Build passes (run project-appropriate build command, e.g., `npm run build`, `mvn compile`, `cargo build`)
+4. Related tests pass
+5. No obvious security issues (no hardcoded secrets, no new unsafe operations)
+
+**Pass standard**: All 5 items OK, no CRITICAL issues.
+
+**When failing**: report failed items, record failure, move back to build, then invoke `/opensuper-build`.
+
+```bash
+bash "$OPENSUPER_STATE" transition <name> verify-fail
+```
+
+**Report format**: Brief table listing 5 check results + PASS/FAIL.
+
+**Skipped items** (not checked in lightweight verification):
+- spec scenario coverage
+- design doc consistency deep comparison
+- code pattern consistency recommendations
+- delta spec and design doc drift detection
+
+### 2b. Full Verification (Large Changes)
+
+When scale assessment result is "large":
+
+**Immediately execute:** Use the Skill tool to load the `openspec-verify-change` skill. Skipping this step is prohibited.
+
+After the skill loads, follow its guidance to verify. Check items:
+1. All tasks in tasks.md completed (`[x]`)
+2. Implementation matches design.md design decisions
+3. Implementation matches brainstorming design document
+4. All capability specification scenarios pass
+5. proposal.md goals satisfied
+6. No contradiction between delta spec and design doc (if Build phase had incremental spec modifications, check if design doc has corresponding records)
+7. `docs/superpowers/specs/` associated design document can be located (file exists and relates to current change)
+
+When verification fails: report missing items, record failure, move back to build, then invoke `/opensuper-build`.
+
+```bash
+bash "$OPENSUPER_STATE" transition <name> verify-fail
+```
+
+**Spec drift handling**:
+- If check item 6 finds contradiction (delta spec has content but design doc doesn't reflect it), prompt user:
+  - Option A: Append "Implementation Divergence" section to design doc recording deviation reason
+  - Option B: Roll back to Build phase, supplement brainstorming to update design doc
+  - Option C: Confirm deviation acceptable, continue verification (design doc will be marked as `superseded-by-main-spec` during archiving)
+
+### 3. Completion (Superpowers)
+
+**Immediately execute:** Use the Skill tool to load the `superpowers:finishing-a-development-branch` skill. Skipping this step is prohibited.
+
+If `superpowers:finishing-a-development-branch` is unavailable, stop the process and prompt to install or enable Superpowers skills. Do not substitute this step with normal conversation.
+
+After the skill loads, follow its guidance to complete. Branch handling options:
+1. Local merge to main branch
+2. Push and create PR
+3. Keep branch (handle later)
+4. Discard work
+
+**Confirmation items**:
+- All tests pass
+- No hardcoded secrets or security issues
+
+## Exit Conditions
+
+- Verification report passed
+- Branch handled
+- **Phase guard**: Run `bash "$OPENSUPER_GUARD" <change-name> verify --apply`; after all PASS, it uses `opensuper-state transition verify-pass` to advance to `phase: archive`
+
+After verification and branch handling are complete, run guard to auto-transition:
+
+```bash
+bash "$OPENSUPER_GUARD" <change-name> verify --apply
+```
+
+State file is automatically updated to `phase: archive`, `verify_result: pass`, `verified_at: YYYY-MM-DD`.
+
+## Automatic Transition
+
+After exit conditions are met, **proceed immediately to the next phase without waiting for user input**:
+
+> **REQUIRED NEXT SKILL:** Invoke `opensuper-archive` skill to enter the archiving phase.

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

@@ -0,0 +1,271 @@
+---
+name: opensuper
+description: "OpenSuper — OpenSpec + Superpowers 双星开发流程。用 /opensuper 启动，自动检测阶段并分发到子命令。五阶段：开启 → 深度设计 → 计划与构建 → 验证与收尾 → 归档。"
+---
+
+# OpenSuper — OpenSpec + Superpowers 双星开发流程
+
+OpenSpec 与 Superpowers 如双星系统围绕同一目标运转。
+
+```
+OpenSpec 负责 WHAT  — 大纲、提案、spec 生命周期、归档
+Superpowers 负责 HOW — 技术设计、计划、执行、收尾
+```
+
+**核心原则：brainstorming 必不可跳过。每次变更都必须经过深度设计（hotfix 和 tweak preset 除外）。**
+
+---
+
+## 决策核心（Decision Core）
+
+agent 做决策只需读本节，参考附录按需查阅。
+
+### 阶段自动检测
+
+**Step 0: 活跃 Change 发现与意图判定**
+
+1. 先做 Preset 检测；命中 hotfix/tweak 时直接调用对应 preset skill，不进入普通 open 分支
+2. 未命中 preset 时，运行 `openspec list --json` 获取所有活跃 change
+
+**Preset 检测优先级最高**：
+- 用户明确描述为 bug fix / 热修复 + 满足 hotfix 条件 → 直接 `/opensuper-hotfix`
+- 用户明确描述为文案/配置/文档/prompt 小调整 + 满足 tweak 条件 → 直接 `/opensuper-tweak`
+- 未命中 preset → 按下表处理
+
+| 活跃 change | 用户输入 | 行为 |
+|-------------|---------|------|
+| 无 | 非 preset 输入 | → 调用 `/opensuper-open` |
+| 恰好 1 个 | `/opensuper <描述>` | → **询问**：继续该变更 or 创建新变更 |
+| 多个 | `/opensuper <描述>` | → **询问**：继续现有变更 or 创建新变更；若选继续 → 列出清单让用户选择 |
+| 恰好 1 个 | `/opensuper`（无描述） | → 自动选中，进入 Step 1 |
+| 多个 | `/opensuper`（无描述） | → 列出清单让用户选择 |
+
+<IMPORTANT>
+当用户选择「创建新变更」时，**必须调用 `/opensuper-open`**（禁止直接调用 `/opsx:new`）。
+`/opensuper-open` 负责完整双初始化：OpenSpec artifacts（由内部 `/opsx:new` 创建）+ `.opensuper.yaml` 状态文件。
+直接调用 `/opsx:new` 会缺失 `.opensuper.yaml`，导致后续阶段判定失败。
+</IMPORTANT>
+
+**Step 1: 读取 `.opensuper.yaml` 状态元数据**
+
+优先读取 `openspec/changes/<name>/.opensuper.yaml`。不存在时回退到 `openspec status --change "<name>" --json`、`tasks.md` 和 `docs/superpowers/` 文件检查。
+
+**断点恢复规则**：
+- 每次恢复上下文时，先重新执行 Step 0 和 Step 1，不依赖对话历史判断阶段
+- 若 `phase: build`，读取 tasks.md 的下一个未勾选任务继续
+- 若 `phase: verify` 且 `verify_result: fail`，先运行 `bash "$OPENSUPER_STATE" transition <name> verify-fail`，再调用 `/opensuper-build`
+- 若 `phase: open` 但 proposal/design/tasks 已完整，先运行 `bash "$OPENSUPER_GUARD" <change-name> open --apply` 修正状态，再继续判定
+- 若 `phase: archive`，只允许调用 `/opensuper-archive`；归档成功后 change 会移动到 archive 目录，不再对原活跃目录运行 guard
+
+**Step 2: 阶段判定**（按顺序，命中即停）
+
+1. `archived: true` 或 change 已移入 archive → 流程已完成
+2. `verify_result: pass` 且 `archived` 不是 `true` → `/opensuper-archive`
+3. `verify_result: fail` → `bash "$OPENSUPER_STATE" transition <name> verify-fail` 后 `/opensuper-build`
+4. `phase: verify` 或 tasks.md 全部勾选 → `/opensuper-verify`
+5. `phase: build` 或已有 Design Doc 但计划/执行未完成 → `/opensuper-build`
+6. `phase: design` 或有 change 但无 Design Doc → `/opensuper-design`
+7. `phase: open` 或有活跃 change 但 `.opensuper.yaml` 缺失 → `/opensuper-open`
+8. 无活跃 change → `/opensuper-open`
+
+如果元数据与文件状态冲突，以文件状态为准，修正 `.opensuper.yaml` 后继续。
+
+### 预设升级条件
+
+**hotfix → full**（满足任一即升级）：
+- 改动涉及 **3+ 文件**
+- 涉及架构变更（新模块、新接口、新依赖）
+- 涉及数据库 schema 变更
+- 修复引入新的 public API
+- 修复范围超出单一函数/模块
+
+**tweak → full**（满足任一即升级）：
+- 改动涉及 **5+ 文件**
+- 涉及多个模块的协调修改
+- 需要新增测试用例 **5+**
+- 涉及配置项的新增或删除（非值修改）
+
+### 错误处理速查
+
+| 场景 | 处理方式 |
+|------|---------|
+| `openspec list --json` 失败 | 检查 openspec 是否已安装，提示 `openspec init` |
+| 子 skill 不可用 | 停止流程，提示安装或启用对应 skill |
+| `.opensuper.yaml` 格式异常或缺失 | 以文件状态为准，用 `bash $OPENSUPER_STATE set` 修正后继续 |
+| 构建/测试失败 | 返回 build 阶段修复，不进入 verify |
+| change 目录结构不完整 | 按 `opensuper-open` 产物要求补齐 |
+
+### 阶段衔接
+
+<IMPORTANT>
+单次 `/opensuper` 调用从检测到的阶段开始，退出条件满足后进入下一阶段。
+
+流转链：open → design → build → verify → archive
+
+**连续执行要求**：从检测到的阶段开始，agent 必须自动走完后续所有阶段，中间不停顿等待用户输入（除非遇到需要用户决策的节点）。每个阶段完成后立即进入下一阶段，无需用户再次输入。
+
+需要用户参与的节点（仅在这些节点暂停）：
+1. brainstorming 确认设计方案
+2. build 阶段选择执行方式
+3. verify 不通过时决定修复或接受偏差
+4. finishing-branch 选择分支处理方式
+5. 遇到升级条件（hotfix/tweak → 完整流程）
+
+agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须自动继续推进，不得中途退出。
+</IMPORTANT>
+
+---
+
+## 子命令速查
+
+| 命令 | 阶段 | 归属 | 产物 |
+|------|------|------|------|
+| `/opensuper-open` | 1. 开启 | OpenSpec | proposal.md、design.md、tasks.md |
+| `/opensuper-design` | 2. 深度设计 | Superpowers | Design Doc、delta spec |
+| `/opensuper-build` | 3. 计划与构建 | Superpowers | 实施计划、代码提交 |
+| `/opensuper-verify` | 4. 验证与收尾 | Both | 验证报告、分支处理 |
+| `/opensuper-archive` | 5. 归档 | OpenSpec | delta→main spec 同步、design doc 标注、归档 |
+| `/opensuper-hotfix` | 预设路径 | Both | 快速修复（跳过 brainstorming） |
+| `/opensuper-tweak` | 预设路径 | Both | 小改动（跳过 brainstorming 和完整 plan） |
+
+```
+/opensuper
+  ↓ 自动检测
+/opensuper-open ──→ /opensuper-design ──→ /opensuper-build ──→ /opensuper-verify ──→ /opensuper-archive
+  (OpenSpec)      (Superpowers)     (Superpowers)     (Both)          (OpenSpec)
+
+/opensuper-hotfix（预设路径，跳过 brainstorming）
+  open ──→ build ──→ verify ──→ archive
+    ↑ 如触发升级条件 → 补充 Design Doc → 回到完整流程
+
+/opensuper-tweak（预设路径，跳过 brainstorming 和完整 plan）
+  open ──→ lightweight build ──→ light verify ──→ archive
+    ↑ 如触发升级条件 → 补充 Design Doc → 回到完整流程
+```
+
+---
+
+## 参考附录（Reference Appendix）
+
+### .opensuper.yaml 字段说明
+
+```yaml
+workflow: full
+phase: build
+design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+build_mode: subagent-driven-development
+isolation: branch
+verify_mode: light
+verify_result: pending
+verification_report: null
+branch_status: pending
+verified_at: null
+archived: false
+```
+
+| 字段 | 含义 |
+|------|------|
+| `workflow` | `full`、`hotfix` 或 `tweak` |
+| `phase` | 当前阶段：`open`、`design`、`build`、`verify`、`archive`（init 统一设为 `open`，guard 负责过渡） |
+| `design_doc` | 关联的 Superpowers Design Doc 路径，可为空 |
+| `plan` | 关联的 Superpowers Plan 路径，可为空 |
+| `build_mode` | 已选择的执行方式，可为空 |
+| `isolation` | `branch` 或 `worktree`，工作区隔离方式。full 初始化可为 `null`，但只允许持续到 `/opensuper-build` Step 3 前；hotfix/tweak 默认 `branch` |
+| `verify_mode` | `light` 或 `full`，可为空 |
+| `verify_result` | `pending`、`pass` 或 `fail` |
+| `verification_report` | 验证报告文件路径，verify 通过前必须指向已存在文件 |
+| `branch_status` | `pending` 或 `handled`，分支处理完成后设为 `handled` |
+| `verified_at` | 验证通过时间，可为空 |
+| `archived` | change 是否已归档 |
+
+可选字段：
+
+| 字段 | 含义 |
+|------|------|
+| `direct_override` | `true`/`false`。full workflow 如需使用 `build_mode: direct`，必须显式设为 `true` |
+| `build_command` | 项目构建命令。guard 优先运行该命令，失败时打印命令输出 |
+| `verify_command` | 项目验证命令。verify guard 优先运行该命令，未配置时回退到构建命令 |
+
+状态机硬约束：
+- `build → verify` 前，`isolation` 必须是 `branch` 或 `worktree`
+- `build → verify` 前，`build_mode` 必须已选择
+- `build_mode: direct` 默认只允许 `hotfix` / `tweak`；full workflow 需要 `direct_override: true`
+- 这些约束同时存在于 `opensuper-guard.sh build --apply` 和 `opensuper-state.sh transition <name> build-complete`
+
+### 脚本定位
+
+OpenSuper 脚本随 skill 包分发在 `opensuper/scripts/` 下。**不硬编码路径** — 定位一次，缓存到环境变量：
+
+```bash
+OPENSUPER_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
+OPENSUPER_GUARD="${OPENSUPER_GUARD:-$(find "${OPENSUPER_SEARCH_ROOTS[@]}" -path '*/opensuper/scripts/opensuper-guard.sh' -type f -print -quit 2>/dev/null)}"
+OPENSUPER_STATE="${OPENSUPER_STATE:-$(find "${OPENSUPER_SEARCH_ROOTS[@]}" -path '*/opensuper/scripts/opensuper-state.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)}"
+
+# 脚本定位失败时停止流程
+if [ -z "$OPENSUPER_GUARD" ] || [ -z "$OPENSUPER_STATE" ] || [ -z "$OPENSUPER_ARCHIVE" ]; then
+  echo "ERROR: OpenSuper scripts not found. Ensure the opensuper skill is installed." >&2
+  echo "Expected path pattern: */opensuper/scripts/opensuper-*.sh under project or platform skill directories" >&2
+  return 1
+fi
+```
+
+**自动状态更新**：guard 支持 `--apply` 参数，验证通过后自动更新 `.opensuper.yaml` 状态字段：
+
+```bash
+bash "$OPENSUPER_GUARD" <change-name> <phase> --apply
+```
+
+`--apply` 内部委托给 `opensuper-state transition`。需要直接表达状态事件时使用：
+
+```bash
+bash "$OPENSUPER_STATE" transition <change-name> open-complete
+bash "$OPENSUPER_STATE" transition <change-name> design-complete
+bash "$OPENSUPER_STATE" transition <change-name> build-complete
+bash "$OPENSUPER_STATE" transition <change-name> verify-pass
+bash "$OPENSUPER_STATE" transition <change-name> verify-fail
+bash "$OPENSUPER_STATE" transition <archive-name> archived
+```
+
+**归档脚本**：一键完成归档全部步骤：
+
+```bash
+bash "$OPENSUPER_ARCHIVE" <change-name>
+```
+
+加载 opensuper 后，agent 应执行以上三条变量赋值一次，后续全程复用 `$OPENSUPER_GUARD`、`$OPENSUPER_STATE`、`$OPENSUPER_ARCHIVE`。
+
+### 文件结构
+
+```
+openspec/                              # OpenSpec — WHAT
+├── config.yaml
+├── changes/
+│   ├── <name>/                        # 活跃 change
+│   │   ├── .openspec.yaml
+│   │   ├── .opensuper.yaml
+│   │   ├── proposal.md                # Why + What
+│   │   ├── design.md                  # 高层架构决策
+│   │   ├── specs/<capability>/spec.md # Delta 能力规格
+│   │   └── tasks.md                   # 任务清单
+│   └── archive/YYYY-MM-DD-<name>/     # 已归档
+└── specs/<capability>/spec.md         # 主 specs（归档时从 delta 覆盖）
+
+docs/superpowers/                      # Superpowers — HOW
+├── specs/YYYY-MM-DD-<topic>-design.md # 设计文档（技术 RFC，归档时标注状态）
+└── plans/YYYY-MM-DD-<feature>.md      # 实施计划（文件头含 change 关联元数据）
+```
+
+### 最佳实践
+
+1. **brainstorming 不可跳过** — 每次变更必须经过深度设计（hotfix 和 tweak 除外）
+2. **delta spec 是活文档** — 阶段 3 期间可自由修改，归档时同步
+3. **保持 tasks.md 同步** — 完成一个勾一个
+4. **频繁提交** — 每个任务一次提交，message 体现设计意图
+5. **先验证再归档** — `/opensuper-verify` 通过后才执行 `/opensuper-archive`
+6. **增量更新分级** — 小编辑、中重 brainstorming、大新 change
+7. **Plan 必须关联 change** — 文件头包含 `change:` 和 `design-doc:` 元数据
+8. **归档闭环** — design doc 和 plan 必须标注 `archived-with` 状态
+9. **修改已有功能** — 直接 open 新 change 即可
+10. **Preset 有上限** — hotfix/tweak 满足升级条件时及时切换到完整流程