@flyin-ai/alloy 0.1.0 → 0.2.0-beta.0

package/commands/alloy/plan.md

@@ -1,6 +1,6 @@
 ---
 name: "Alloy: Plan"
-description: Alloy 规划阶段——将 draft.md 转化为结构化制品，始终分步，每步可审查
+description: Alloy 规划阶段 - draft.md 完成后进入
 category: Workflow
 tags: [alloy, workflow]
 ---
@@ -9,38 +9,52 @@ tags: [alloy, workflow]
 
 你是 Alloy 的规划阶段编排器。你的职责是按 OpenSpec schema DAG 依赖顺序，制品生成设计文档，每步生成后提供审查窗口。
 
+**核心原则：按 schema DAG 依赖顺序逐一产出制品，每步有审查闸门，不跳过上游直接产下游。**
+
+**交互风格：** 所有审查窗口和用户选择使用 `AskUserQuestion` 工具（箭头选、Enter 确认），不用纯文本 "(a)(b)"。详见 `commands/alloy/references/interaction-style.md`。
+
 **调用外部命令或技能前，先输出标题和状态描述，再执行操作。不要只出标题然后沉默。**
 
+**什么算"plan 执行不到位"（反例）：**
+- 用户说"一次性生成"就直接出全部制品——跳过了 5 个审查窗口，失去了需求验证的时机
+- 用户说"太慢了"就加速跳过审查——审查时间远小于返工时间
+- 用户说"我看过 draft 了，内容都对"就松懈——draft 审查不能替代 proposal/design/specs/tasks 的逐级审查
+
+### Red Flags——STOP，必须分步审查
+
+| 借口 | 现实 |
+|------|------|
+| "一次性生成全部制品，提高效率" | plan 不提供一键生成。5 个制品 = 5 个审查窗口。每步审查的价值远大于省下的几秒。跳过审查 = 跳过需求验证。 |
+| "太慢了，直接出全部吧" | 审查时间远小于后期返工时间。一个未审查的 specs 缺陷到 apply 阶段才发现，代价是重做全部代码。 |
+| "我看过 draft 了，后面的不用看了" | draft 是方案设计，proposal 是提案范围，design 是技术方案，specs 是行为契约——四个层面不可互相替代。 |
+| "这个项目很小，不需要那么正式" | 小项目和大项目的闸门完全一样。不存在"规模分级的保护等级"。 |
+
+**捕获阶段启动时间**（命令调用后第一时间，前置检查之前，幂等——重入时返回已有值）：
+```bash
+PHASE_START=$(alloy _state timestamp ensure openspec/changes/<name> plan)
+```
+
+---
+
 ## 前置检查
 
 1. 确认 change 目录 `openspec/changes/<name>/` 存在且 `.alloy.yaml` phase 为 `started`（由 `/alloy:start` 完成），否则报错
 2. 若 change 目录存在但 `draft.md` 缺失 → 异常状态，提示重新运行 `/alloy:start`
 3. 若指定 `[name]` 参数但 change 不存在 → "未找到 change '<name>'，请先运行 `/alloy:start <name>` 创建 change"
-4. **Skill / 命令预检：** 确认 `opsx:continue` 和 `superpowers:writing-plans` 均可用。任一不可用 → 引导 `alloy init` → STOP。不在生成过程中才暴露缺失。
+4. **Skill / 命令预检：** 确认以下依赖可用：
+   cmd: opsx/continue
+   skill: writing-plans
 
----
+   读取 `commands/alloy/references/skill-precheck.md` 了解检测方法。任一不可用 → 引导 `alloy init` → STOP。
 
-## Step 1/3：确认 Change
+---
 
-**记录阶段开始时间**（用于计算耗时）：
-```bash
-COMPLETED_AT=$(date "+%Y-%m-%d %H:%M:%S")
-TIMINGS=$(alloy _state read openspec/changes/<name> phase_timings 2>/dev/null || echo "{}")
-echo "$TIMINGS" | python3 -c "
-import sys,json
-content = sys.stdin.read()
-d = json.loads(content) if content.strip() else {}
-p = d.setdefault('plan',{})
-if 'started_at' not in p:
-    p['started_at']='$COMPLETED_AT'
-print(json.dumps(d))
-" | while read -r val; do alloy _state write openspec/changes/<name> phase_timings "$val"; done
-```
+### [Step 1/3] 确认 Change
 
 ```
 ┌──────────────────────────────────────┐
 │ Alloy [2/5] · Phase: Plan            │
-│ 启动时间: 从 phase_timings.plan.started_at 读取
+│ 启动时间: $PHASE_START
 └──────────────────────────────────────┘
 
 [Step 1/3] 确认 Change
@@ -51,7 +65,7 @@ print(json.dumps(d))
    ```bash
    git log -1 --format="%s" -- openspec/changes/<name>/draft.md
    ```
-   若 commit message 不含 `feat(<name>): draft 已确认`→ ⚠️ draft.md 可能未经过完整 `/alloy:start` 流程（手工创建），提示用户确认是否继续。不阻断——但给用户知情权。
+   若 commit message 不含 `docs(<name>): draft 已确认`→ ⚠️ draft.md 可能未经过完整 `/alloy:start` 流程（手工创建），提示用户确认是否继续。不阻断——但给用户知情权。
 2. 确认 `.alloy.yaml` phase 为 `started`：
    ```bash
    alloy _state check openspec/changes/<name> started
@@ -60,34 +74,22 @@ print(json.dumps(d))
    ```bash
    git rev-parse --git-dir
    ```
-   若失败 → 项目还不是 git 仓库，引导用户初始化：
-   ```
-   git init && git add -A && git commit -m "chore: 初始提交"
-   ```
+   若失败 → HARD STOP："项目还不是 git 仓库。请先运行 `/alloy:start` 完成初始化（包含 git init）。"
 
-前置检查通过：draft.md ✓  phase=started ✓  git ✓
+前置检查通过：draft.md ✓  phase=started ✓  git ✓  技能 ✓
 
 **若 phase 不匹配（phase != started）：**
 
-先读取当前 phase，按以下规则自动路由：
-
-| 当前 phase | 行为 |
-|-----------|------|
-| planned | "plan 已完成，自动进入 /alloy:apply" → 加载 alloy-apply 指令 |
-| applied | "已进入执行阶段，自动进入 /alloy:apply" → 加载 alloy-apply 指令 |
-| archived | "已归档，自动进入 /alloy:finish" → 加载 alloy-finish 指令 |
-| finished | "工作流已完成" → STOP |
-
-**实现方式：** 输出对应命令文件的完整指令，将 change name 和当前进度信息作为上下文传入。
+读取 `commands/alloy/references/phase-routing.md` 按路由表自动跳转。实现方式：输出对应命令文件的完整指令，将 change name 和当前进度信息作为上下文传入。
 
 **若 change 目录不存在或 draft.md 缺失：**
 → 引导用户先运行 `/alloy:start <name>` 创建 change。这是唯一保留 HARD STOP 的场景——前序阶段完全没做。
 
 ---
 
-## Step 2/3：制品生成 · /opsx:continue + writing-plans
+### [Step 2/3] 制品生成 · /opsx:continue + writing-plans
 
-**[Step 2/3] 制品生成**
+[Step 2/3] 制品生成
 ──────────────────────────────────────
 
 **每个制品（proposal / design / specs / tasks）必须通过 `/opsx:continue` 生成。禁止手动编写制品文件。** `/opsx:continue` 自动读取 schema DAG，按 `proposal → design → specs → tasks` 顺序依次产出，每次调用生成一个制品。**tasks 是 `/opsx:continue` 生成的最后一个制品。**plans.md 由 `superpowers:writing-plans` 技能生成（见下文）。
@@ -143,19 +145,69 @@ done
 
 制品全部完成（plans.md 存在且 hash 有效）时，phase 推进到 planned，提示下一步。
 
+**不要输出全局制品进度**（如"0/8 artifacts 完成"）。[N/M] 是阶段内局部编号（M=5），不反映全局进度。全局进度由 `alloy status` 命令管理。
+
 ### 正常推进：逐个制品的审查流程
 
-每个制品生成后，展示内容并进入审查窗口。**仅两个选项——不跳过。** 审查窗口使用块引用格式（终端有底色渲染）：
+每个制品生成后，展示内容并进入审查窗口。**仅两个选项——不跳过。**
+
+审查窗口分两步：**先**用 markdown 文本展示制品完整内容（审查窗口块引用），**后**用 `AskUserQuestion` 工具让用户确认（radio，2 个 option）。不要用纯文本 "(a)(b)" 等用户打字。
+
+**制品 [1/5] proposal：**
+
+> 制品 [1/5] proposal ✓ 完成
+>
+> [展示 proposal.md 完整内容]
+>
+> → 下一个：design（依赖 proposal + draft.md）
+>
+> → (a) 确认，锁定 proposal 并继续 design
+> → (b) 需要调整 — 说明修改点
+
+**制品 [2/5] design：**
+
+> 制品 [2/5] design ✓ 完成
+>
+> [展示 design.md 完整内容]
+>
+> → 下一个：specs（依赖 proposal）
+>
+> → (a) 确认，锁定 design 并继续 specs
+> → (b) 需要调整 — 说明修改点
+
+**制品 [3/5] specs：**
 
 > 制品 [3/5] specs ✓ 完成
 >
-> [展示制品完整内容]
+> [展示 specs/ 完整内容]
 >
 > → 下一个：tasks（依赖 specs + design）
 >
 > → (a) 确认，锁定 specs 并继续 tasks
 > → (b) 需要调整 — 说明修改点
 
+**制品 [4/5] tasks：**
+
+> 制品 [4/5] tasks ✓ 完成
+>
+> [展示 tasks.md 完整内容]
+>
+> → 下一个：plans（依赖 tasks）
+>
+> → (a) 确认，锁定 tasks 并继续生成 plans
+> → (b) 需要调整 — 说明修改点
+
+**制品 [5/5] plans：**
+
+> 制品 [5/5] plans ✓ 完成
+>
+> [展示 plans.md 完整内容]
+>
+> → plan 阶段完成
+>
+> → (a) 确认，锁定 plans 并完成 plan 阶段
+> → (b) 需要调整 — 说明修改点
+
 **审查窗口只展示制品内容，不打印 OpenSpec schema 的 instructions 模板。** instructions 是给 Agent 的内部指引，不是给用户审查的输出。
 
 - **选 (a)**：当前制品锁定，进入下一个制品或阶段
@@ -169,7 +221,7 @@ done
   - 需求层面变更（功能增删、行为变更、范围调整）→ 内部标记为需求变更
 
   无论 AI 如何判断，始终向用户呈现相同的 (a)/(b) 两个选项。
-  用户选 (a) → 执行回溯清理步骤，加载 `superpowers:brainstorming`。
+  用户选 (a) → 执行回溯清理步骤，加载 `superpowers:brainstorming`。brainstorming 负责重新讨论需求，用户确认后回到这里继续生成制品（不是 invoke writing-plans——那是独立使用 brainstorming 时的行为）。
   用户选 (b) → 回到当前审查窗口，重新展示 (a) 确认 / (b) 需要调整 选项。
 
 **什么算"审查不充分"（反例）：**
@@ -181,6 +233,11 @@ done
 
 每个制品审批通过（用户选 a）后，立即 hash 锁定并 commit：
 
+**hash 锁定前，记录技能使用：**
+```bash
+alloy _skill log openspec/changes/<name> plan opsx:continue
+```
+
 ```bash
 HASH=$(alloy _record compute openspec/changes/<name> <artifact>)
 APPROVED_AT=$(date "+%Y-%m-%d %H:%M:%S")
@@ -190,6 +247,20 @@ git add openspec/changes/<name>/
 git commit -m "docs(<name>): <artifact> 已确认"
 ```
 
+**plans 是 plan 阶段最后一个制品。** plans 审批通过后，phase_timings + hash-lock 合并为**一个 commit**——禁止拆成两次提交：
+
+```bash
+# 写入完成时间 + hash 锁定 + 提交，一气呵成
+COMPLETED_AT=$(date "+%Y-%m-%d %H:%M:%S")
+alloy _state merge openspec/changes/<name> phase_timings "{\"plan\":{\"completed_at\":\"${COMPLETED_AT:-$(date '+%Y-%m-%d %H:%M:%S')}\"}}"
+HASH=$(alloy _record compute openspec/changes/<name> plans)
+APPROVED_AT=$(date "+%Y-%m-%d %H:%M:%S")
+APPROVER=$(alloy _record approver openspec/changes/<name>)
+alloy _record write openspec/changes/<name> plans "$HASH" "$APPROVED_AT" "$APPROVER"
+git add openspec/changes/<name>/
+git commit -m "docs(<name>): plans 已确认"
+```
+
 commit message 格式：`docs(<change-name>): <artifact> 已确认`（Conventional Commits `docs` type）。`<artifact>` 为 proposal / design / specs / tasks / plans。
 
 **生成下一制品前，校验上游依赖制品的 hash 未被篡改：**
@@ -215,6 +286,11 @@ tasks 审批通过并 commit 后，**加载 `superpowers:writing-plans` 技能**
 >
 > alloy 不在 plan 阶段额外询问策略选择——writing-plans 的决策直接保留在 frontmatter 中，apply 阶段再读取并给用户确认。
 
+**技能加载后立即记录：**
+```bash
+alloy _skill log openspec/changes/<name> plan superpowers:writing-plans
+```
+
 writing-plans 完成并保存 plans.md（含 strategy frontmatter）后，直接进入 plans 审查窗口。frontmatter 格式：
 
 ```yaml
@@ -226,7 +302,7 @@ reason: <writing-plans 执行交接环节的策略分析理由>
 ...
 ```
 
-plans.md 生成后展示审查窗口，审批通过后 hash 锁定并 commit。
+plans.md 生成后展示审查窗口，审批通过后先写入 phase_timings.completed_at，再 hash 锁定并 commit（phase_timings 作为元数据附着在 plans 制品提交上，不单独 commit）。
 
 ### 回溯修改：修改已确认的上游制品
 
@@ -253,21 +329,23 @@ rm -rf openspec/changes/<name>/specs/
 # 2. 清理 records（只保留 draft）
 DRAFT_RECORD=$(alloy _state read openspec/changes/<name> records | python3 -c "
 import sys,json
-records = json.loads(sys.stdin.read() or '[]')
+content = sys.stdin.read().strip()
+records = json.loads(content) if content and content != 'null' else []
 draft = [r for r in records if r.get('artifact') == 'draft']
 print(json.dumps(draft))
 ")
 alloy _state write openspec/changes/<name> records "$DRAFT_RECORD"
 
 # 3. 清理 phase_timings（清除 plan/apply/archive/finish 记录，重置 start.completed_at）
+# ⚠️ 此处是 phase_timings 唯一允许 _state write 的场景：回溯需要删除 key + 覆盖值，merge 语义不支持。
+# 所有其他 phase_timings 更新必须使用 _state merge，禁止 _state write。
 TIMINGS=$(alloy _state read openspec/changes/<name> phase_timings 2>/dev/null || echo "{}")
 echo "$TIMINGS" | python3 -c "
 import sys,json
-d = json.loads(sys.stdin.read() or '{}')
-# 清除下游阶段
+content = sys.stdin.read().strip()
+d = json.loads(content) if content and content != 'null' else {}
 for k in ['plan','apply','archive','finish']:
     d.pop(k, None)
-# 重置 start 完成时间——start 重新变为进行中
 if 'start' in d:
     d['start']['completed_at'] = None
 print(json.dumps(d))
@@ -284,30 +362,13 @@ git commit -m "chore(<name>): 回溯——清理 plan 制品，回到 brainstorm
 
 ---
 
-## Step 3/3：完成
+### [Step 3/3] 完成
 
 先读取所有 record 的时间戳用于汇总展示：
 ```bash
 alloy _state read openspec/changes/<name> records
 ```
 
-**记录阶段完成时间：**
-```bash
-COMPLETED_AT=$(date "+%Y-%m-%d %H:%M:%S")
-TIMINGS=$(alloy _state read openspec/changes/<name> phase_timings 2>/dev/null || echo "{}")
-echo "$TIMINGS" | python3 -c "
-import sys,json
-content = sys.stdin.read()
-d = json.loads(content) if content.strip() else {}
-p = d.setdefault('plan',{})
-if 'completed_at' not in p:
-    p['completed_at']='$COMPLETED_AT'
-print(json.dumps(d))
-" | while read -r val; do alloy _state write openspec/changes/<name> phase_timings "$val"; done
-git add openspec/changes/<name>/
-git commit -m "chore(<name>): 记录 plan 阶段完成时间"
-```
-
 ```
 ┌──────────────────────────────────────┐
 │ Alloy [2/5] · Phase: Plan — DONE     │
@@ -358,3 +419,4 @@ guard 校验 hash 一致性后自动推进 phase。如果 guard 返回非零，
 - **制品生成完成后必须通过 alloy _guard 校验** —— 脚本检查 started→planned 转换的合法性及 hash 一致性
 - **plans 完成后不要自动进入 apply** —— 给用户空间审视完整规划
 - **plan 阶段调整统一回 brainstorming** —— 需求/设计层面的任何变更从 draft 根重新审视，不做就地修补。typo/措辞修正除外。apply 阶段的 verify/retrospective 只修代码不改规格
+- **不输出全局制品进度** — [N/M] 是阶段内局部编号（M=5），不要输出"N/8 artifacts 完成"。全局进度由 `alloy status` 管理

package/commands/alloy/references/interaction-style.md

@@ -0,0 +1,82 @@
+# Alloy 交互风格指南
+
+Alloy 各阶段需要用户输入时，**优先使用平台原生的交互式选择工具**。纯文本 "(a)(b)(c)" 只是换了格式的开放式提问——用户还是要打字。原生交互组件让用户用箭头选、空格勾、Enter 提交，一次按键完成决策。
+
+## 平台工具对照
+
+| 平台 | 交互式选择工具 | 能力 |
+|------|-------------|------|
+| **Claude Code** | `AskUserQuestion` | radio（单选）、checkbox（多选）、preview（代码对比） |
+| **Codex** | 无等价工具 | 降级为结构化文本选项 |
+| **Copilot CLI** | 无等价工具 | 降级为结构化文本选项 |
+| **Gemini CLI** | 查平台工具映射 | 查 GEMINI.md 中的工具映射 |
+
+**降级策略：** 当平台无原生交互工具时，使用清晰的文本选项格式——但必须结构化（每选项一行，带编号和简短说明），不要让用户猜要输入什么。
+
+## 选择类型与工具映射
+
+| 场景 | `AskUserQuestion` 配置 | 示例 |
+|------|----------------------|------|
+| **审查确认** (a/b 二元) | `multiSelect: false`，2 个 option | (a) 确认，锁定并继续 / (b) 需要调整 |
+| **多选一** (3-4 选项) | `multiSelect: false`，3-4 个 option | 分支选择、策略选择、技术方案选型 |
+| **范围确认** (独立选项) | `multiSelect: true`，空格勾选 | 功能范围、carry-forward items、边界确认 |
+| **方案对比** (含代码差异) | `multiSelect: false` + `preview` 字段 | 架构方案 A vs B，preview 展示代码结构差异 |
+
+## 审查窗口标准模式
+
+制品审查是 Alloy 最常见的交互场景。遵循以下模式：
+
+1. **先展示内容**——用 markdown 文本展示制品完整内容（审查窗口本身，不能被交互工具替代）
+2. **再让用户确认**：
+
+**Claude Code（推荐）：**
+```
+AskUserQuestion: {
+  questions: [{
+    question: "确认并锁定 <制品名>？",
+    header: "<制品名>",
+    options: [
+      { label: "(a) 确认，锁定并继续", description: "hash 锁定 + commit，进入下一制品" },
+      { label: "(b) 需要调整", description: "说明修改点" }
+    ],
+    multiSelect: false
+  }]
+}
+```
+
+**其他平台（降级）：**
+```
+> → (a) 确认，锁定 <制品名> 并继续
+> → (b) 需要调整 — 说明修改点
+> 请输入 a 或 b：
+```
+
+**硬规则：凡是技能文件中出现 `AskUserQuestion` JSON 块的，同一位置必须附带降级文本格式。** Agent 执行时先检测当前平台是否支持 `AskUserQuestion` 工具——支持则用原生交互组件，不支持则自动降级为文本选项。两个格式给出相同选项、相同数量，确保不同平台上用户看到的选项一致。
+
+**反例：** 审查窗口只用文本 "(a) 确认 (b) 调整" 而不给明确的输入提示——用户不知道是要打字、复制粘贴还是直接说"确认"。
+
+## 不能使用 AskUserQuestion 的场景
+
+以下场景**保持精确文本确认**，因为它们是安全机制而非便利功能：
+
+- **破坏性操作确认**（discard、merge 确认）：用户必须输入精确字符串 `discard <name>` 或 `merge <branch> into <branch>`
+- **已由外部技能处理的交互**：如 `finishing-a-development-branch` 技能的合并策略选择
+
+## 提问密度
+
+- `AskUserQuestion` 一次最多 4 个问题，相关问题**合并到一次调用**
+- 不要一个问题调一次——那是文本选项的思维
+- 每次选项的 `description` 写清楚选这个意味着什么，让用户无需额外思考
+
+## 各阶段适用场景速查
+
+| 阶段 | 主要 AskUserQuestion 场景 |
+|------|--------------------------|
+| start | 探查方向选择（radio）、需求范围确认（checkbox）、draft 审查（radio） |
+| plan | 5 个制品审查窗口（radio）、回溯确认（radio） |
+| apply | 分支异常处理（radio）、执行策略选择（radio）、verify/retrospective 审查（radio） |
+| finish | 主分支确认（radio） |
+| fix | 诊断确认（radio）、主分支确认（radio）、hotfix 合并确认（精确文本） |
+| archive | 无用户交互（全自动） |
+| status | 无用户交互（只读） |
+| discard | **不使用**——保持精确文本确认 |

package/commands/alloy/references/main-branch-detection.md

@@ -0,0 +1,32 @@
+# 主分支检测
+
+start 和 fix 命令共享的主分支自动检测逻辑。
+
+## 检测优先级（3 级）
+
+```bash
+# 1. remote HEAD（标准默认分支）
+DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||')
+# 2. 本地 init.defaultBranch 配置
+[ -z "$DEFAULT_BRANCH" ] && DEFAULT_BRANCH=$(git config --get init.defaultBranch 2>/dev/null)
+# 3. 名称匹配（main 或 master）
+[ -z "$DEFAULT_BRANCH" ] && DEFAULT_BRANCH=$(git branch --list 'main' --list 'master' | head -1 | sed 's/[* ]//g')
+```
+
+## 配置优先
+
+若 `openspec/config.yaml` 已有 `alloy.main_branch` 记录，直接用记录值，跳过检测和确认。
+
+## 确认步骤
+
+检测到主分支后，必须让用户确认（Y/n）：
+```
+主分支: $DEFAULT_BRANCH。使用此分支作为基础分支？[Y/n]
+```
+
+选 Y 或直接回车 → 使用检测结果。选 n → 让用户输入自定义名称。
+
+确认后写入项目级配置：
+```bash
+alloy _config write <project-root> main_branch <用户确认的主分支名>
+```

package/commands/alloy/references/phase-routing.md

@@ -0,0 +1,21 @@
+# Phase 路由表
+
+所有 alloy 阶段命令共享的 phase 自动路由规则。当 `alloy _guard` 检测到 phase 不匹配时，按此表自动跳转到正确阶段。
+
+## 路由表
+
+| 当前 phase | 行为 |
+|-----------|------|
+| started | 尚未 plan → 加载 alloy-plan 指令 |
+| planned | 尚未 apply → 加载 alloy-apply 指令 |
+| applied | 尚未 archive → 加载 alloy-archive 指令 |
+| archived | 尚未 finish → 加载 alloy-finish 指令 |
+| finished | 工作流已完成 → STOP |
+
+## 实现方式
+
+输出对应命令文件的完整指令（`commands/alloy/plan.md` / `apply.md` / `archive.md` / `finish.md`），将 change name 和当前进度信息作为上下文传入。Agent 无缝进入对应阶段。
+
+## HARD STOP 保留场景
+
+change 目录不存在（前序阶段完全没做）→ 引导用户先运行 `/alloy:start`。这是唯一保留 HARD STOP 的场景。

package/commands/alloy/references/skill-precheck.md

@@ -0,0 +1,46 @@
+# Skill 预检脚本
+
+所有 alloy 阶段命令共享的技能/命令可用性检测脚本。各命令传入自己的技能列表即可。
+
+## 使用方式
+
+在命令中按以下格式声明所需依赖，然后执行下方预检脚本：
+
+```
+Skill 预检——确认以下可用：
+  cmd: opsx/explore opsx/new
+  skill: brainstorming
+```
+
+## 预检脚本
+
+将上面声明的 cmd 和 skill 列表填入脚本中的对应位置：
+
+```bash
+MISSING=0
+
+# 检测 command（project → user）
+for cmd in <cmd列表>; do
+  if test -f ".claude/commands/$cmd.md"; then echo "  ✓ ${cmd//\//:}（项目级 command）"
+  elif test -f "$HOME/.claude/commands/$cmd.md"; then echo "  ✓ ${cmd//\//:}（用户级 command）"
+  else echo "  ✗ ${cmd//\//:} — 未找到"; MISSING=$((MISSING+1)); fi
+done
+
+# 检测 skill（project skill → user skill → user plugin）
+for skill in <skill列表>; do
+  if test -d ".claude/skills/$skill"; then echo "  ✓ superpowers:$skill（项目级 skill）"
+  elif test -d "$HOME/.claude/skills/$skill"; then echo "  ✓ superpowers:$skill（用户级 skill）"
+  elif for d in "$HOME/.claude/plugins/cache/superpowers-marketplace/superpowers/"*"/skills/$skill"; do test -d "$d" && break; done 2>/dev/null; then echo "  ✓ superpowers:$skill（用户级 plugin）"
+  else echo "  ✗ superpowers:$skill — 未找到"; MISSING=$((MISSING+1)); fi
+done
+
+if [ "$MISSING" -gt 0 ]; then echo ""; echo "  需要先完成环境初始化。请运行: alloy init"; exit 1; fi
+```
+
+## 检测优先级
+
+项目级 command → 项目级 skill → 用户级 command → 用户级 skill → 用户级 plugin
+
+任一不可用 → 引导 `alloy init` → STOP。
+
+**如果某命令只有 command 或只有 skill 依赖，省略对应的 for 循环即可。**