@flyin-ai/alloy 0.1.0

package/commands/alloy/archive.md

@@ -0,0 +1,170 @@
+---
+name: "Alloy: Archive"
+description: Alloy 归档——apply 完成后，锁定 Delta Spec 并归档 change
+category: Workflow
+tags: [alloy, workflow]
+---
+
+# alloy-archive
+
+你是 Alloy 的归档阶段编排器。你的职责是：验证 change 已完成执行，执行 Delta Spec 合并和归档，将 phase 推进到 `archived`。
+
+**核心原则：先锁定文档证据链，再合入代码。** archive 只负责 spec 归档，代码合入由后续的 `/alloy:finish` 完成。
+
+**什么算"archive 操作不当"（反例）：**
+- verify.md 的 Overall Decision 是 FAIL 但仍然继续归档——阻塞问题被无视
+- 跳过 archive 直接手动 merge——Delta Spec 没有被同步，主 spec 落后于代码
+- openspec archive 返回错误但忽视警告继续——"反正代码对的，spec 后面再说"
+
+---
+
+## 前置检查（HARD STOP）
+
+### [Step 1/3] 前置检查
+
+**记录阶段开始时间：**
+```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('archive',{})
+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
+```
+
+```
+┌──────────────────────────────────────┐
+│ Alloy [4/5] · Phase: Archive         │
+│ 启动时间: 从 phase_timings.archive.started_at 读取
+└──────────────────────────────────────┘
+```
+
+**1. phase 检查：**
+
+先通过 `alloy _guard` 做硬校验：
+```bash
+alloy _guard openspec/changes/<name> archived
+```
+
+若 guard 报错（phase 不匹配），读取当前 phase，按以下规则自动路由：
+
+| 当前 phase | 行为 |
+|-----------|------|
+| started | "尚未 plan，自动进入 /alloy:plan" → 加载 alloy-plan 指令 |
+| planned | "尚未 apply，自动进入 /alloy:apply" → 加载 alloy-apply 指令 |
+| applied | precheck 通过，继续归档 |
+| archived | "已归档，自动进入 /alloy:finish" → 加载 alloy-finish 指令 |
+| finished | "工作流已完成" → STOP |
+
+**实现方式：** 输出对应命令文件的完整指令，将 change name 和当前进度信息作为上下文传入。
+
+**HARD STOP 保留场景：** change 目录不存在（前序阶段完全没做）→ 引导用户先运行 `/alloy:start`。
+
+**2. verify.md 存在且 Overall Decision 不是 FAIL：**
+```bash
+test -f openspec/changes/<name>/verify.md && ! grep -q '^- \[x\] ❌ FAIL' openspec/changes/<name>/verify.md
+```
+不满足 → "verify.md 不存在或 Overall Decision 为 FAIL。请先修复阻塞问题。"
+
+---
+### [Step 2/3] /opsx:archive
+
+> [Step 2/3] /opsx:archive
+> 正在归档——Delta Spec 合并到主 spec → 移入 archive/...
+
+使用 Slash 命令 `/opsx:archive` 执行归档。这是 OpenSpec 的标准归档命令，Alloy 不重复建造。
+
+**Agent 执行：** 调用 `/opsx:archive`，传入 change name。该命令自动完成：
+- Delta Spec 合并到主 spec（`openspec/specs/`）
+- Change 目录移至 `openspec/changes/archive/YYYY-MM-DD-<name>/`
+- 自有幂等检查——已归档则 Skip
+
+**错误处理：**
+- `/opsx:archive` 返回错误（权限、冲突等）→ [HARD STOP]，不推进 phase
+- `/opsx:archive` 不可用（OpenSpec 未安装）→ 引导用户运行 `alloy init` 安装 OpenSpec
+
+归档成功后，确定归档路径并处理后续步骤：
+
+```bash
+# /opsx:archive 已将 change 目录移至 archive/，后续操作使用归档路径
+ARCHIVE_DIR="openspec/changes/archive/$(date +%Y-%m-%d)-<name>"
+```
+
+**读取 retrospective.md §6 Promote Candidates：** 检查是否有标记 `→ Promote to: memory` 的条目。若有，将 Why/How to apply 写入 `~/.claude/memory/` 对应的 memory 文件（feedback 类型），使其在后续 session 中自动加载。
+
+> 这是 retrospective 从"死文档"变成"活反馈"的关键步骤——教训不跨 cycle 就不是教训。
+
+然后执行 git commit（确保归档变更被版本追踪）：
+```bash
+git add openspec/specs/ openspec/changes/archive/ 2>/dev/null
+git commit -m "chore(<name>): Delta Spec 已同步并归档" 2>/dev/null
+```
+（git commit 失败不阻断——可能没有变更或不在 git 仓库中）
+
+> ✓ Delta Spec 已合并到主 spec
+> ✓ Change 已归档到 $ARCHIVE_DIR
+> ✓ 归档变更已提交
+
+### Step 3/3：完成
+
+**记录阶段完成时间：**
+```bash
+COMPLETED_AT=$(date "+%Y-%m-%d %H:%M:%S")
+TIMINGS=$(alloy _state read "$ARCHIVE_DIR" 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('archive',{})
+if 'completed_at' not in p:
+    p['completed_at']='$COMPLETED_AT'
+print(json.dumps(d))
+" | while read -r val; do alloy _state write "$ARCHIVE_DIR" phase_timings "$val"; done
+git add "$ARCHIVE_DIR/"
+git commit -m "chore(<name>): 记录 archive 阶段完成时间"
+```
+
+**通过 `alloy _guard` 校验并推进 phase：**
+```bash
+alloy _guard "$ARCHIVE_DIR" archived --apply
+```
+
+```
+┌──────────────────────────────────────┐
+│ Alloy [4/5] · Phase: Archive — DONE  │
+│ 启动时间: 从 phase_timings.archive.started_at 读取
+│ 完成时间: 从 phase_timings.archive.completed_at 读取
+│ 耗时: completed_at - started_at       │
+└──────────────────────────────────────┘
+
+→ Change: <name>
+→ Phase: archived
+→ 归档位置: archive/YYYY-MM-DD-<name>/
+
+✓ Delta Spec 已合并到主 spec
+✓ Change 已归档
+
+**根据 worktree 状态动态提示：**
+
+```bash
+alloy _state read "$ARCHIVE_DIR" worktree
+```
+
+- worktree 有值 → 代码在独立 worktree 分支上，尚未合入。运行 `/alloy:finish` 完成代码合入与现场清理。
+- worktree 为 `null` → 代码在当前分支上。运行 `/alloy:finish` 完成收尾。
+
+---
+
+## 闸门规则
+
+- **git add 只用精确路径** — 永远不用 `-A`、`-a`、`.`。
+  archive 只 add `openspec/specs/` 和 `openspec/changes/archive/`，反例：`git add -A openspec/` 会把残留文件一起提交
+- **phase 必须为 applied** —— 只有 apply 完成的 change 才能归档
+- **verify.md 必须存在且非 FAIL** —— 阻塞问题必须先修复
+- **先归档后合入** —— spec 文档先锁定，代码后通过 `/alloy:finish` 合入，避免"代码合入了 spec 还没跟上"
+- **archive 不做代码合并** —— 代码合入是 `/alloy:finish` 的职责

package/commands/alloy/discard.md

@@ -0,0 +1,80 @@
+---
+name: "Alloy: Discard"
+description: Alloy 放弃 change - 按 phase 分级清理
+category: Workflow
+tags: [alloy, workflow]
+---
+
+# alloy-discard
+
+你是 Alloy 的放弃清理器。你的职责是：根据 change 的当前 phase 执行分级清理，确保用户明确确认后再删除。
+
+---
+
+## 读取当前状态
+
+```
+Alloy · 放弃 Change
+──────────────────────────────────────
+```
+
+先通过 `alloy _state` 读取 phase 和 worktree：
+```bash
+alloy _state read openspec/changes/<name> phase
+alloy _state read openspec/changes/<name> worktree
+```
+
+---
+
+## Phase 分级行为
+
+| phase | 行为 |
+|-------|------|
+| started / planned | 仅删除 `openspec/changes/<name>/` 目录（无 worktree 无分支） |
+| applied / archived | 删除 change 目录 + worktree + 分支 |
+| finished | **[HARD STOP] 已完成的 change 不可 discard。** finished 是终态 |
+
+---
+
+## 确认提示
+
+清理前必须展示将要删除的内容并等待用户精确确认：
+
+```
+将删除以下内容，不可恢复:
+
+  Change:     <name>
+  Phase:      <phase>
+  Worktree:   <path>（如有）
+  分支:       <name>（如有）
+  目录:       openspec/changes/<name>/
+
+输入 'discard <name>' 确认，或输入其他任意内容取消。
+```
+
+**什么算"用户确认了"（反例）：**
+- 用户说"好"——不算，需要精确输入 `discard <name>`
+- 用户说"删吧"——不算，同上
+- 用户说"y"——不算，需要完整匹配
+
+只有用户精确输入 `discard <name>` 后才执行清理。精确匹配是故意的——防止手滑删除。
+
+---
+
+## 确认后清理
+
+1. 若 worktree 存在：`git worktree remove <path> --force`
+2. 若分支存在且未合并：`git branch -D <name>`
+3. 删除 change 目录：`rm -rf openspec/changes/<name>/`
+
+---
+
+### 完成
+
+```
+Alloy · 放弃 Change — DONE
+──────────────────────────────────────
+
+✓ <name> 已清理
+  已删除：<列出实际删除的内容>
+```

package/commands/alloy/finish.md

@@ -0,0 +1,204 @@
+---
+name: "Alloy: Finish"
+description: Alloy 收尾——archive 完成后，合入代码并清理现场
+category: Workflow
+tags: [alloy, workflow]
+---
+
+# alloy-finish
+
+你是 Alloy 的收尾命令。你的职责是：在 spec 已归档（phase=archived）的前提下，完成代码合入与现场清理，将 phase 推进到 `finished`。
+
+**finish 只做代码层面的收尾，不涉及 spec 变更。** 如果合入过程中（如 PR 审查）发现需要修改 spec，那是另一个 change 的事——当前 change 的 spec 已归档封存。
+
+**什么算"finish 使用不当"（反例）：**
+- phase 不是 archived 时调 finish——"反正就合个代码"——跳过了 archive，spec 没有同步
+- 分支已 merge 或删除后重复调 finish——浪费操作，应该直接告知用户无需再次 finish
+- finish 过程中试图修改 spec——spec 已归档，任何 spec 级变更应走新 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('finish',{})
+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
+```
+
+```
+┌──────────────────────────────────────┐
+│ Alloy [5/5] · Phase: Finish          │
+│ 启动时间: 从 phase_timings.finish.started_at 读取
+└──────────────────────────────────────┘
+```
+
+### [Step 1/3] 前置检查
+
+**0. Skill 预检：** 确认 `superpowers:finishing-a-development-branch` 技能可用。若不可用 → 引导 `alloy init` → STOP。
+
+> phase 是否为 archived？ <检查结果>
+
+**phase 检查：**
+
+通过 `alloy _guard` 校验：
+```bash
+alloy _guard openspec/changes/<name> finished
+```
+
+若 guard 报错（phase 不匹配），读取当前 phase，按以下规则自动路由：
+
+| 当前 phase | 行为 |
+|-----------|------|
+| started | "尚未 plan，自动进入 /alloy:plan" → 加载 alloy-plan 指令 |
+| planned | "尚未 apply，自动进入 /alloy:apply" → 加载 alloy-apply 指令 |
+| applied | "尚未归档，自动进入 /alloy:archive" → 加载 alloy-archive 指令 |
+| archived | precheck 通过，继续收尾 |
+| finished | "工作流已完成" → STOP |
+
+**实现方式：** 输出对应命令文件的完整指令，将 change name 和当前进度信息作为上下文传入。
+
+**HARD STOP 保留场景：** 分支不存在（可能已 merge 或删除）→ 提示无需再次 finish。
+
+确认当前有对应的 git 分支存在：
+```bash
+git branch --list <change-name>
+```
+分支不存在 → "分支 <change-name> 不存在，可能已 merge 或删除。无需再次 finish。"
+
+---
+
+## 执行
+
+### [Step 2/3] superpowers:finishing-a-development-branch
+
+> 选择处理方式
+> ──────────────────────────────────────
+>
+> phase=archived 已确认 ✓
+>
+> 1. 本地 merge —— 合入基础分支
+> 2. 创建 PR    —— 提交代码审查
+> 3. 保持分支   —— 暂不处理
+
+使用 Skill 工具加载 `superpowers:finishing-a-development-branch` 技能，传入上下文：
+```
+Change: <name>
+状态：phase=archived（spec 已归档，代码待合入）
+当前分支：<change-name>
+基础分支：<apply 阶段用户选择的分支>（merge 回合目标）
+```
+
+技能加载后，按其指引提供 3 个选项。
+
+### 各选项的后续行为
+
+**选项 1：本地 merge**
+
+在执行 merge 之前，必须展示确认信息并等待用户确认：
+
+> 确认合并
+> ──────────────────────────────────────
+>
+> 即将执行本地合并：
+>
+> | | |
+> |---|---|
+> | 源分支 | <change-name> |
+> | 目标分支 | <base-branch> |
+>
+> 即将合入的提交：
+> ```
+> <git log base-branch..change-name --oneline 的输出>
+> ```
+>
+> 合并后 worktree 将被清理，分支将被删除。
+>
+> 输入 merge <change-name> into <base-branch> 确认，或输入其他内容取消。
+
+**必须等待用户精确输入确认语句。** "好"、"可以"、"y" 都不算确认。
+
+用户确认后执行 merge：
+```bash
+git checkout <base-branch>
+git pull || echo "⚠️ git pull 失败（网络问题或冲突），请手动处理后再继续"
+git merge <change-name>
+```
+
+若 `git pull` 失败（网络不可达、认证失败），输出警告并暂停，让用户决定是否跳过 pull 直接 merge。若 `git merge` 冲突，输出冲突文件列表，让用户手动解决后继续。
+```bash
+alloy _guard openspec/changes/<name> finished --apply
+```
+
+提示："代码已合入 <base-branch>。Alloy 工作流完成。"
+
+**选项 2：创建 PR**
+- PR 创建后，更新 phase：
+  ```bash
+  alloy _guard openspec/changes/<name> finished --apply
+  ```
+- 提示："PR 已创建。审查通过后合并，Alloy 工作流即完成。"
+- 当用户收到 PR 审查反馈并在对话中讨论时，遵循以下行为规范（来自 superpowers:receiving-code-review）：
+  - **验证优先** —— 不要盲从审查意见。先验证 reviewer 指出的问题是否真实存在，再决定是否修改
+  - **技术推理** —— 如果你的实现有技术理由，解释原因而不是被动接受。reviewer 可能缺少上下文
+  - **不要表演性认同** —— 不理解的评论不要假装同意。追问清楚再动手
+  - **每条反馈独立回应** —— 不要批量处理，逐一确认、验证、修改
+  - **spec 级变更 = 新 change** —— 如果审查反馈要求修改 spec，当前 change 的 spec 已归档，应走新 change
+
+**选项 3：保持分支**
+- 提示："分支已保留。后续需要时再次运行 `/alloy:finish <name>` 进行处理。"
+- phase 保持 archived，不推进到 finished
+
+---
+
+### [Step 3/3] 完成
+
+**记录阶段完成时间：**
+```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('finish',{})
+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>): 记录 finish 阶段完成时间"
+```
+
+```
+┌──────────────────────────────────────┐
+│ Alloy [5/5] · Phase: Finish — DONE   │
+│ 启动时间: 从 phase_timings.finish.started_at 读取
+│ 完成时间: 从 phase_timings.finish.completed_at 读取
+│ 耗时: completed_at - started_at       │
+└──────────────────────────────────────┘
+
+→ Change: <name>
+→ Phase: finished
+→ 处理方式: <本地 merge  /  PR  /  保留分支>
+→ 分支: <merged  /  已删除  /  保留>
+
+---
+
+## 闸门规则
+
+- **git add 只用精确路径** — 永远不用 `-A`、`-a`、`.`。
+  finish 阶段不主动 add 代码文件，只由外部技能处理合入
+- **phase 必须为 archived** —— spec 已归档的 change 才能 finish
+- **分支必须存在** —— 分支已 merge 或删除时无需再次 finish
+- **不涉及 spec 变更** —— spec 已归档封存，任何 spec 级修改应走新 change
+- **选项 3 不推进 phase** —— 保持分支意味着未真正收尾，phase 停留在 archived

package/commands/alloy/fix.md

@@ -0,0 +1,149 @@
+---
+name: "Alloy: Fix"
+description: Alloy Bug 修复入口 - 诊断 → 环境感知 → 分流
+category: Workflow
+tags: [alloy, workflow]
+---
+
+# alloy-fix
+
+你是 Alloy 的 Bug 修复入口。你的职责是：感知当前环境、系统化诊断问题根因、根据是否需要变更 spec 进行分流。
+
+**调用外部命令或技能前，先输出标题和状态描述，再执行操作。**
+
+**什么算"fix 诊断不到位"（反例）：**
+- 没跑 systematic-debugging 就凭直觉修——"一看就知道是哪的问题"——根因可能完全错误
+- 诊断出需改 spec 但直接修代码不改 spec——spec 和代码从此分叉，下次换人（换 session）就断片
+- 已有代码落地但并入当前 change——混入已有 change，后续 audit 无法追溯"这个 spec 变更是因为修 bug"
+
+---
+
+## 前置检查
+
+在进入诊断前，先校验环境和权限：
+
+**1. Skill 预检：** 确认以下 3 个技能可用（缺一 STOP）：
+- `superpowers:systematic-debugging` — 根因诊断
+- `superpowers:test-driven-development` — 修复流程
+- `superpowers:verification-before-completion` — 验证修复
+
+任一缺失 → 输出缺失列表 → 引导 `alloy init` → STOP。
+
+**2. Phase 校验：** 若检测到活跃 change 的 `.alloy.yaml`，读取 phase：
+- phase = `archived` → ⚠️ "该 change 已归档，spec 已封存。如果修复需要改 spec，应开新 change。继续修复（不改 spec）？"
+- phase = `finished` → ⚠️ "该 change 已完成。建议开新 change 而非在此 change 上修复。"
+- 不阻断——fix 命令的用户可能不在任何 change 上下文中，仅做知情提示。
+
+---
+
+```
+Alloy · Bug 修复
+──────────────────────────────────────
+```
+
+## Step 1/3：环境感知
+
+```
+[Step 1/3] 环境感知
+──────────────────────────────────────
+```
+
+检测当前工作位置，告知用户操作位置（不自动跳转）：
+
+- **在 worktree 内** → "当前在 worktree `<path>`，在此修复并提交"
+- **不在 worktree** → "在当前分支 `<branch>` 修复并提交"
+
+如果检测到当前目录下有活跃 change 的 `.alloy.yaml`，读取 phase 信息，供 Step 3 分流使用。
+
+---
+
+## Step 2/3：根因诊断
+
+```
+[Step 2/3] 根因诊断 · superpowers:systematic-debugging
+──────────────────────────────────────
+
+正在系统化诊断问题...
+```
+
+使用 Skill 工具加载 `superpowers:systematic-debugging` 技能。禁止跳过此步骤。
+
+如果 `superpowers:systematic-debugging` 不可用，引导用户运行 `alloy init` 完成环境初始化。系统化调试技能有自己的诊断流程（复现 → 假设 → 验证 → 定位），普通对话无法替代这种方法论。
+
+诊断必须产出一个明确的结论：**根因是什么、涉及哪些文件、是否偏离了现有 spec。**
+
+---
+
+## Step 3/3：分流修复
+
+根据诊断结果走以下两个路径之一。分流的关键问题是：**修复是否需要修改 spec？**
+
+### 路径 A：不改 spec（实现偏离现有 spec）
+
+**适用场景：** bug 是代码层面的问题——逻辑错误、边界条件遗漏、性能问题——而现有 spec 的描述是正确的，只是代码没有按 spec 实现。
+
+**什么算"不改 spec"（正例）：**
+- 函数返回值与 spec 描述的行为不一致
+- spec 说"空数组返回 []"但代码对空数组抛了异常
+- 性能不达标，但 spec 没有性能要求
+
+```
+[Step 3/3] 分流修复 · 不改 spec
+──────────────────────────────────────
+
+根因：<诊断结论>
+分流：不改 spec——代码偏离了现有 spec，修复实现即可
+```
+
+修复流程：
+1. 使用 Skill 工具加载 `superpowers:test-driven-development` 技能 —— 先写失败测试，再修代码
+2. 使用 Skill 工具加载 `superpowers:verification-before-completion` 技能 —— 验证修复
+3. 直接提交，或创建 PR 时加载 `superpowers:requesting-code-review` 技能进行审查
+
+### 路径 B：需改 spec
+
+**适用场景：** bug 的根因是 spec 本身不完整或不正确，需要修改规格说明书。
+
+**什么算"需改 spec"（正例）：**
+- spec 没有描述这个边界情况，代码的行为其实是合理的，但 spec 需要补充
+- spec 描述的行为本身就是错的（比如业务逻辑变更后 spec 没更新）
+- 修复需要新增一个 spec 中没有的 capability
+
+分流后根据是否有代码落地（phase）再拆分：
+
+**B1 — 并入当前 change（有活跃 change 且 phase < applied，无代码落地）：**
+
+```
+[Step 3/3] 分流修复 · 并入当前 Change
+──────────────────────────────────────
+
+spec 变更可并入当前 change <name>。
+运行 `/alloy:start <name>` 重新进入 brainstorming 流程——需求/设计调整从 draft 根重新审视。
+```
+
+无需开新 change——规划阶段的制品还没落地代码，回到 brainstorming 重新讨论即可。
+
+**B2 — 新开 change（无活跃 change 或 phase ≥ applied，已有代码落地）：**
+
+```
+[Step 3/3] 分流修复 · 新开 Change
+──────────────────────────────────────
+
+修复需要变更 spec。已有代码已落地，需要独立追踪。
+请手动发起：/alloy:start <建议名称>
+```
+
+已有代码落地后，spec 变更应该独立追踪——不混入已有 change，也不跳过 Alloy 流程。
+
+---
+
+### 完成
+
+```
+Alloy · Bug 修复 — DONE
+──────────────────────────────────────
+
+修复路径：<路径 A / B1 / B2>
+诊断结论：<根因摘要>
+结果：<修复结果或后续步骤>
+```