@flyin-ai/alloy 0.1.0

package/commands/alloy/plan.md

@@ -0,0 +1,360 @@
+---
+name: "Alloy: Plan"
+description: Alloy 规划阶段——将 draft.md 转化为结构化制品，始终分步，每步可审查
+category: Workflow
+tags: [alloy, workflow]
+---
+
+# alloy-plan
+
+你是 Alloy 的规划阶段编排器。你的职责是按 OpenSpec schema DAG 依赖顺序，制品生成设计文档，每步生成后提供审查窗口。
+
+**调用外部命令或技能前，先输出标题和状态描述，再执行操作。不要只出标题然后沉默。**
+
+## 前置检查
+
+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。不在生成过程中才暴露缺失。
+
+---
+
+## 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
+```
+
+```
+┌──────────────────────────────────────┐
+│ Alloy [2/5] · Phase: Plan            │
+│ 启动时间: 从 phase_timings.plan.started_at 读取
+└──────────────────────────────────────┘
+
+[Step 1/3] 确认 Change
+──────────────────────────────────────
+```
+
+1. 确认 `openspec/changes/<name>/draft.md` 存在，并验证来源：
+   ```bash
+   git log -1 --format="%s" -- openspec/changes/<name>/draft.md
+   ```
+   若 commit message 不含 `feat(<name>): draft 已确认`→ ⚠️ draft.md 可能未经过完整 `/alloy:start` 流程（手工创建），提示用户确认是否继续。不阻断——但给用户知情权。
+2. 确认 `.alloy.yaml` phase 为 `started`：
+   ```bash
+   alloy _state check openspec/changes/<name> started
+   ```
+3. 确认 git 仓库可用：
+   ```bash
+   git rev-parse --git-dir
+   ```
+   若失败 → 项目还不是 git 仓库，引导用户初始化：
+   ```
+   git init && git add -A && git commit -m "chore: 初始提交"
+   ```
+
+前置检查通过：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 和当前进度信息作为上下文传入。
+
+**若 change 目录不存在或 draft.md 缺失：**
+→ 引导用户先运行 `/alloy:start <name>` 创建 change。这是唯一保留 HARD STOP 的场景——前序阶段完全没做。
+
+---
+
+## Step 2/3：制品生成 · /opsx:continue + writing-plans
+
+**[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` 技能生成（见下文）。
+
+作为编排器，你的职责是在每次 `/opsx:continue` 生成制品后插入审查窗口。**始终分步，不提供一键生成。**
+
+**执行方式：** 使用 Skill 工具加载 `opsx:continue` 技能，传入 change name。`opsx:continue` 自动获取 schema 指令并生成对应的制品文件——不要自行编写制品内容，不要一次生成多个制品。
+
+如果 `/opsx:continue` 不可用，引导用户运行 `alloy init` 完成环境初始化。
+
+**制品 DAG 及依赖关系：**
+```
+proposal ──→ design ──→ specs ──→ tasks ──→ plans
+    │                      ↑
+    └──────────────────────┘
+```
+
+| 制品 | 依赖 | 被依赖 |
+|------|------|--------|
+| proposal | draft.md | design, specs |
+| design | proposal + draft.md | specs, tasks |
+| specs | proposal（只读 Capabilities） | tasks |
+| tasks | specs + design | plans |
+| plans | tasks | — |
+
+**注意：plans.md 是执行脚本，非规格文档。** 规格（specs/）是行为契约，plans.md 是给 Agent 执行的微步骤路线图（可含代码片段）。
+
+### 制品进度扫描
+
+在调用 `/opsx:continue` 之前，先扫描哪些制品已完成（文件存在 + hash 有效）：
+
+```bash
+# 扫描已完成制品
+for artifact in proposal design specs tasks plans; do
+  if alloy _record check openspec/changes/<name> "$artifact" 2>/dev/null; then
+    echo "  $artifact ✓"
+  else
+    echo "  $artifact ✗"
+  fi
+done
+```
+
+根据扫描结果，从第一个缺失的制品开始生成：
+
+```
+制品进度扫描:
+  proposal  ✓ hash 有效 → 跳过
+  design    ✓ hash 有效 → 跳过
+  specs     ✗ → 从 specs 开始生成
+
+→ /opsx:continue 从第一个缺失制品开始
+```
+
+制品全部完成（plans.md 存在且 hash 有效）时，phase 推进到 planned，提示下一步。
+
+### 正常推进：逐个制品的审查流程
+
+每个制品生成后，展示内容并进入审查窗口。**仅两个选项——不跳过。** 审查窗口使用块引用格式（终端有底色渲染）：
+
+> 制品 [3/5] specs ✓ 完成
+>
+> [展示制品完整内容]
+>
+> → 下一个：tasks（依赖 specs + design）
+>
+> → (a) 确认，锁定 specs 并继续 tasks
+> → (b) 需要调整 — 说明修改点
+
+**审查窗口只展示制品内容，不打印 OpenSpec schema 的 instructions 模板。** instructions 是给 Agent 的内部指引，不是给用户审查的输出。
+
+- **选 (a)**：当前制品锁定，进入下一个制品或阶段
+- **选 (b)**：用户说明修改点后，AI 内部评估修改性质，然后呈现确认选项：
+
+  > → (a) 确认变更，回溯到 brainstorming
+  > → (b) 取消变更，继续当前审查
+
+  **AI 判断指南（内部推理，不对外展示标签）：**
+  - typo/措辞修正（错别字、格式调整、表达优化，不改变功能边界）→ 内部标记为轻量变更
+  - 需求层面变更（功能增删、行为变更、范围调整）→ 内部标记为需求变更
+
+  无论 AI 如何判断，始终向用户呈现相同的 (a)/(b) 两个选项。
+  用户选 (a) → 执行回溯清理步骤，加载 `superpowers:brainstorming`。
+  用户选 (b) → 回到当前审查窗口，重新展示 (a) 确认 / (b) 需要调整 选项。
+
+**什么算"审查不充分"（反例）：**
+- 只问了一句"看起来可以吗？"没有展示实际内容
+- 用户说"继续"但没有明确说"确认"
+- 用户不明确表态时催促用户给出 (a) 或 (b)
+
+### 每制品审批后 hash + commit
+
+每个制品审批通过（用户选 a）后，立即 hash 锁定并 commit：
+
+```bash
+HASH=$(alloy _record compute openspec/changes/<name> <artifact>)
+APPROVED_AT=$(date "+%Y-%m-%d %H:%M:%S")
+APPROVER=$(alloy _record approver openspec/changes/<name>)
+alloy _record write openspec/changes/<name> <artifact> "$HASH" "$APPROVED_AT" "$APPROVER"
+git add openspec/changes/<name>/
+git commit -m "docs(<name>): <artifact> 已确认"
+```
+
+commit message 格式：`docs(<change-name>): <artifact> 已确认`（Conventional Commits `docs` type）。`<artifact>` 为 proposal / design / specs / tasks / plans。
+
+**生成下一制品前，校验上游依赖制品的 hash 未被篡改：**
+```bash
+alloy _record check openspec/changes/<name> <upstream-artifact>
+```
+若 check 返回非零 → HARD STOP，hash 不匹配意味着有未审批的篡改。
+
+| 即将生成的制品 | 需校验的上游 |
+|--------------|------------|
+| design | proposal |
+| specs | proposal |
+| tasks | specs, design |
+| plans | tasks |
+
+### tasks 审批通过后 → writing-plans 生成 plans.md
+
+tasks 审批通过并 commit 后，**加载 `superpowers:writing-plans` 技能**生成 plans.md。
+
+> 使用 Skill 工具加载 `superpowers:writing-plans` 技能，将 tasks + specs + design 作为上下文传入。**遵循 writing-plans 的完整原始流程**——从文件结构设计、任务拆解、代码填充，到末尾的"执行交接"。writing-plans 自行决定执行策略并写入 plans.md YAML frontmatter（`strategy` + `reason` 字段）。
+>
+> **注意：** writing-plans 默认保存路径为 `docs/superpowers/plans/`，Alloy 要求将 plans.md 保存到 `openspec/changes/<name>/plans.md`。加载 writing-plans 时需显式指定此路径。
+>
+> alloy 不在 plan 阶段额外询问策略选择——writing-plans 的决策直接保留在 frontmatter 中，apply 阶段再读取并给用户确认。
+
+writing-plans 完成并保存 plans.md（含 strategy frontmatter）后，直接进入 plans 审查窗口。frontmatter 格式：
+
+```yaml
+---
+strategy: sdd
+reason: <writing-plans 执行交接环节的策略分析理由>
+---
+# 执行计划
+...
+```
+
+plans.md 生成后展示审查窗口，审批通过后 hash 锁定并 commit。
+
+### 回溯修改：修改已确认的上游制品
+
+plan 阶段处理的是"构建什么"——任何制品一旦审批通过，不允许就地修改。需求/设计层面的调整都应从 draft 根重新审视，而非打补丁。
+
+**规则——统一回到 brainstorming：**
+
+| 要修改的制品 | 行为 |
+|------------|------|
+| draft / proposal / design / specs / tasks / plans | 清理 plan 制品 → 回到 brainstorming |
+
+> apply 阶段的需求变更见 apply.md 的"需求变更处理"闸门——以 tasks.md checkbox 状态判断是否允许回溯。verify/retrospective 验证"代码是否匹配规格"，发现问题修正代码，不改变需求/设计。
+
+**回溯清理步骤：**
+
+```bash
+# 1. 删除 plan 制品文件（保留 draft.md）
+rm -f openspec/changes/<name>/proposal.md
+rm -f openspec/changes/<name>/design.md
+rm -f openspec/changes/<name>/tasks.md
+rm -f openspec/changes/<name>/plans.md
+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 '[]')
+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）
+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 '{}')
+# 清除下游阶段
+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))
+" | 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 制品，回到 brainstorming"
+```
+
+```
+→ 制品已清理（仅保留 draft），records/phase_timings 已重置
+→ 请运行 /alloy:start <name> 重新走需求确认流程
+```
+
+---
+
+## 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     │
+│ 启动时间: 从 phase_timings.plan.started_at 读取
+│ 完成时间: 从 phase_timings.plan.completed_at 读取
+│ 耗时: completed_at - started_at       │
+└──────────────────────────────────────┘
+
+→ Change: <name>
+→ Phase: planned
+
+所有制品已生成并锁定：
+
+  制品             状态    Hash          创建时间
+  ──────────────  ────    ────────────  ───────────────────
+  draft           ✓       <hash>        <timestamp>
+  proposal        ✓       <hash>        <timestamp>
+  design          ✓       <hash>        <timestamp>
+  specs           ✓       <hash>        <timestamp>
+  tasks           ✓       <hash>        <timestamp>
+  plans           ✓       <hash>        <timestamp>
+```
+
+每个制品已在审批时独立 commit，无需再次提交。
+
+**通过 `alloy _guard` 校验并更新 phase：**
+
+```bash
+alloy _guard openspec/changes/<name> planned --apply
+```
+
+guard 校验 hash 一致性后自动推进 phase。如果 guard 返回非零，检查缺哪个制品或 hash 是否不匹配。
+
+```
+制品文件禁止手动修改。如需变更，回到 brainstorming 在当前 change 内重新讨论。
+
+准备好后，运行 `/alloy:apply` 进入执行阶段。
+```
+
+---
+
+## 闸门规则
+
+- **git add 只用精确路径** — 永远不用 `-A`、`-a`、`.`。
+  反例：`git add .` 或 `git commit -am "fix"` 会把 `todo.py`、`tasks.json` 等意外文件一起提交
+- **始终分步，不提供一键生成** —— 每个制品必须单独审查确认后才能继续。跳过审查等于跳过需求验证，后期返工代价远大于审查时间
+- **每制品审批后必须 hash 锁定 + commit** —— 不可篡改追踪，确保审计链完整
+- **制品生成完成后必须通过 alloy _guard 校验** —— 脚本检查 started→planned 转换的合法性及 hash 一致性
+- **plans 完成后不要自动进入 apply** —— 给用户空间审视完整规划
+- **plan 阶段调整统一回 brainstorming** —— 需求/设计层面的任何变更从 draft 根重新审视，不做就地修补。typo/措辞修正除外。apply 阶段的 verify/retrospective 只修代码不改规格

package/commands/alloy/start.md

@@ -0,0 +1,314 @@
+---
+name: "Alloy: Start"
+description: Alloy 智能入口 - 自动检测状态，接续或新建 change
+category: Workflow
+tags: [alloy, workflow]
+---
+
+# alloy-start
+
+你是 Alloy 工作流的智能入口。你的职责是：检测当前状态、路由到正确流程、调度外部技能完成探查和需求设计，最后产出 draft.md。
+
+**核心原则：把实际工作委托给专门的技能，不要自己做。Alloy 是编排器，不是执行者。**
+
+> **`<TIMESTAMP>` 的含义：** 每次渲染阶段头部框时，执行 `date "+%Y-%m-%d %H:%M:%S"` 获取本地时间，替换 `<TIMESTAMP>`。不要输出字面字符串 `<TIMESTAMP>`。`<SESSION_START>` 是"全新开始"路径在 header 渲染前捕获的会话启动时间，后续 step 8 写入 phase_timings 时复用该值。`<created_at>` 从 `.alloy.yaml` 的 `created_at` 字段读取。
+
+---
+
+## 状态检测
+
+**第一步：检查项目是否就绪。** 检查 `openspec/config.yaml` 是否存在——这是项目已初始化 OpenSpec 的唯一标记。
+
+如果 `openspec/config.yaml` 不存在，说明项目尚未初始化。引导用户运行 `alloy init` 完成项目级初始化。OpenSpec 技能可以全局共享，但 `openspec/` 目录是每个项目的"身份证"——必须在项目中创建。
+
+**第二步：扫描活跃 change。** 扫描 `openspec/changes/*/.alloy.yaml`，统计 phase != `finished` 的 change。
+
+---
+
+## 全新开始（无活跃 change + 用户提供了 topic）
+
+**记录会话启动时间**（后续写入 phase_timings.start.started_at）：
+```bash
+echo "SESSION_START=$(date "+%Y-%m-%d %H:%M:%S")"
+```
+
+```
+┌──────────────────────────────────────┐
+│ Alloy [1/5] · Phase: Start           │
+│ 启动时间: 使用上面 SESSION_START 的值
+└──────────────────────────────────────┘
+```
+
+### [Step 1/2] 上下文探查
+
+> 正在探查项目上下文和需求空间...
+
+**立即执行：** 使用 Skill 工具加载 `opsx:explore` 技能。禁止跳过此步骤。
+
+如果 `opsx:explore` 不可用（OpenSpec 未安装或命令不存在），引导用户运行 `alloy init` 完成环境初始化。
+
+技能加载后，按其指引自由探索项目上下文和需求空间。
+
+**额外上下文——来自历史 retrospective 的教训：** 在探查阶段，扫描 `openspec/changes/archive/` 下最近 3 个已归档 change 的 `retrospective.md`，提取以下信息作为本次 brainstorming 的参考：
+
+- **§5 意外发现**：上一次有哪些假设被推翻？这次可能也有类似盲区
+- **§6 值得推广**：有哪些未勾选的 carry-forward item？这次可以直接勾上
+- **§4 技能跳过模式**：如果连续两个 retrospective 中同一技能被 ✗，提醒用户该技能可能不适合本项目
+
+> 这些信息不是约束——只是在 brainstorming 时提醒 Agent 和用户"上次我们踩了这个坑"。
+
+---
+
+### [Step 2/2] 需求设计
+
+> 正在启动 brainstorming...
+
+**前置预检：** 确认 `superpowers:brainstorming` 技能可用。若不可用 → 引导用户运行 `alloy init` 重新安装 → STOP。不在 Step 2 才发现缺失。
+
+**立即执行：** 使用 Skill 工具加载 `superpowers:brainstorming` 技能。禁止跳过此步骤。
+
+将探查结果作为 ARGUMENTS 传入：
+```
+探查结果：<Step 1 的关键发现摘要>
+主题：<topic>
+项目类型：<新项目/存量项目>
+```
+
+技能加载后，按其指引进行交互式需求设计。
+
+如果 `superpowers:brainstorming` 不可用，引导用户运行 `alloy init` 完成环境初始化。brainstorming 技能内置了审批闸门和 Q&A 深度——普通对话无法复现这些行为。
+
+**brainstorming 完成后，你必须等待用户确认方案，然后生成 `draft.md`：**
+
+```markdown
+# [功能名称]
+
+## Why
+<!-- 要解决的问题 -->
+
+## What
+<!-- 方案概述 -->
+
+## 关键决策
+<!-- 关键技术决策及理由 -->
+<!-- 将 brainstorming 的详细设计论述写入此章节，不单独产出 superpowers spec 文件 -->
+
+## 范围与边界
+<!-- 做什么、明确不做什么 -->
+```
+
+**关键：** brainstorming 的所有设计论述（方案对比、技术决策、架构考量）全部写入 draft.md 的"关键决策"章节。不单独在 `docs/superpowers/specs/` 生成文件——draft.md 是 brainstorming 的唯一产出。
+
+**用户明确确认方案之前，不要生成 draft.md。** 如果用户要求调整方案，回到 brainstorming 继续讨论，不要急于产出文件。
+
+**什么算"用户确认了"（反例）：**
+- 用户说"还行"、"可以"——追问他是否满意关键决策和范围边界
+- 用户只确认了部分内容——确保所有关键决策都被明确认可
+
+---
+
+用户确认方案后，执行以下步骤：
+
+1. **建议 change name**——根据确认的方案建议 kebab-case 名称，用户确认
+2. **调用 `/opsx:new <name>`** 创建 change 目录
+3. **按模板生成 `draft.md`** 到 `openspec/changes/<name>/draft.md`（直接在 change 目录下生成，无需移动）
+4. **写入 state**——使用 `_state init` 一步创建完整初始状态（包含 `records: []`、正确类型），避免逐字段写入遗漏 records 数组：
+   ```bash
+   alloy _state init openspec/changes/<name>
+   ```
+5. **确保 git 仓库就绪：**
+
+   ```bash
+   if ! git rev-parse --git-dir 2>/dev/null; then
+     git init
+     # 空项目：先提交基础设施作为锚点，确保 HEAD 存在以便后续创建分支
+     git add .claude/ .gitignore openspec/config.yaml openspec/schemas/ 2>/dev/null
+     [ -f CLAUDE.md ] && git add CLAUDE.md 2>/dev/null
+     git commit -m "chore: alloy init 项目初始化"
+   fi
+   ```
+
+   已有项目则跳过（git repo 已存在，HEAD 已有锚点）。
+
+6. **分支选择**——检测 git 状态，确认工作分支：
+
+   先获取当前分支：
+   ```bash
+   CURRENT_BRANCH=$(git branch --show-current)
+   echo "当前分支：$CURRENT_BRANCH"
+   ```
+
+   展示选项，让用户选择：
+
+   > 选择工作分支
+   > ──────────────────────────────────────
+   >
+   > 当前在 `<$CURRENT_BRANCH>` 分支
+   >
+   > 1. 在当前分支继续 —— 直接在此分支开发
+   > 2. 切换到已有分支 —— 选择一个已有分支
+   > 3. 新建分支       —— 创建新分支并切换
+   >
+   > → 建议新建 `<change-name>` 分支，保持 main 干净
+
+   - **选 1：** 不操作，直接继续
+   - **选 2：** 展示已有分支列表（`git branch -a`），用户选择后执行 `git checkout <branch>`
+     - 如果该 change 后续使用 worktree，此分支名仅作参考记录
+   - **选 3：** 询问用户输入新分支名，执行 `git checkout -b <new-branch>`
+     - Agent 可建议分支名（如 `<change-name>`），由用户确认
+
+   分支选择完成后，记录到状态：
+   ```bash
+   alloy _state write openspec/changes/<name> worktree null
+   ```
+
+   > ⚠️ apply 阶段仍会通过 `using-git-worktrees` 再次确认隔离方式。此处的分支选择是给后续阶段一个推荐的开发分支。
+
+7. **提交：**
+
+   **draft hash + commit：**
+   ```bash
+   DRAFT_HASH=$(alloy _record compute openspec/changes/<name> draft)
+   APPROVED_AT=$(date "+%Y-%m-%d %H:%M:%S")
+   APPROVER=$(git config user.name)
+   alloy _record write openspec/changes/<name> draft "$DRAFT_HASH" "$APPROVED_AT" "$APPROVER"
+   git add openspec/changes/<name>/
+   git commit -m "feat(<name>): draft 已确认"
+   ```
+
+   **alloy init 基础设施提交：**
+   ```bash
+   git add .claude/ .gitignore openspec/config.yaml openspec/schemas/ 2>/dev/null
+   [ -f CLAUDE.md ] && git add CLAUDE.md 2>/dev/null
+   git diff --cached --quiet || git commit -m "chore: alloy init 项目初始化"
+   ```
+   已提交过则自动跳过。`.superpowers/` 已在 `.gitignore` 中忽略，不入仓库。
+
+8. **记录阶段时间：**
+   ```bash
+   COMPLETED_AT=$(date "+%Y-%m-%d %H:%M:%S")
+   # STARTED_AT 使用步骤开始时捕获的 SESSION_START 值
+   STARTED_AT="<SESSION_START>"
+   alloy _state write openspec/changes/<name> phase_timings "{\"start\":{\"started_at\":\"$STARTED_AT\",\"completed_at\":\"$COMPLETED_AT\"}}"
+   git add openspec/changes/<name>/
+   git commit -m "chore(<name>): 记录 start 阶段完成时间"
+   ```
+
+---
+
+### 完成
+
+```
+┌──────────────────────────────────────┐
+│ Alloy [1/5] · Phase: Start — DONE    │
+│ 启动时间: 从 phase_timings.start.started_at 读取               │
+│ 完成时间: 从 phase_timings.start.completed_at 读取                │
+│ 耗时: XmXs                           │
+└──────────────────────────────────────┘
+
+→ Change: <name>
+→ Phase: started
+
+所有制品已生成并锁定：
+
+  制品             状态    Hash          创建时间
+  ──────────────  ────    ────────────  ───────────────────
+  draft           ✓       <hash>        <timestamp>
+
+准备好后，运行 /alloy:plan 进入规划阶段。
+```
+
+- draft.md 已在 change 目录，项目根目录不再有 draft.md
+- 完成后不要自动进入 plan
+
+---
+
+## 闸门规则
+
+- **git add 只用精确路径** — 永远不用 `-A`、`-a`、`.`。
+  start 阶段只 add `openspec/changes/<name>/` 和 init 基础设施文件（`.claude/` `.gitignore` `openspec/config.yaml` `openspec/schemas/`）；反例：`git add -A` 会把临时文件一起提交
+- **draft.md 必须在 change 目录内** — 不在项目根目录产生临时文件
+
+---
+
+## 自由探索（无活跃 change + 无 topic）
+
+```
+┌──────────────────────────────────────┐
+│ Alloy [1/5] · Phase: Start           │
+│ 启动时间: <TIMESTAMP>            │
+└──────────────────────────────────────┘
+```
+
+### [Step 1/2] 扫描项目上下文
+
+扫描项目上下文（README、已有代码、requirement.md、OpenSpec spec 文件等）。
+
+### [Step 2/2] 呈现发现与建议
+
+**有上下文可读时：** 总结项目信息（技术栈、已有功能、最近变更），基于发现给用户 2-3 个建议方向或追问。目标是帮用户明确他想做什么，而不是抛回一句"请提供主题"。
+
+**空项目无可读上下文时：** 直接告诉用户："项目较新，没有太多上下文可供参考。请用 `/alloy:start <topic>` 重新调用，我会进入完整的需求设计流程。"
+
+> 关键：必须让用户重新输入 `/alloy:start <topic>`，而不是只输入 topic 文本。只有重新调用命令，alloy:start 技能才会被重新加载并进入"全新开始"路径。如果用户只输入 topic 文本而不带命令，Agent 将脱离 alloy:start 编排框架，导致关键闸门（change name 确认、分支选择、hash commitment）被跳过。
+
+---
+
+## 强制新建（--new <topic>）
+
+无论是否有活跃 change，直接走"全新开始"流程。多个 change 可并行 planning，但不能同时 apply（一个 session 只能有一个工作中的 worktree）。
+
+---
+
+## 接续（有 1 个活跃 change）
+
+```
+┌──────────────────────────────────────┐
+│ Alloy [1/5] · Phase: Start           │
+│ 启动时间: 从 phase_timings.start.started_at 读取，若无则从 created_at 读取            │
+└──────────────────────────────────────┘
+
+→ 检测到活跃 change：<name>
+→ 当前阶段：<phase>
+→ 已完成制品：<列出已有文件>
+→ 下一步：<建议操作>
+```
+
+### [Step 1/1] 状态展示与自动接续
+
+先读取 `.alloy.yaml` 获取 phase 和 worktree 字段，再检查文件系统确认实际制品状态。
+
+展示检测结果后，根据 phase 和制品状态决定路由：
+
+| phase | 制品状态 | 自动加载命令 |
+|-------|---------|-------------|
+| started | proposal.md 存在 | alloy-plan（正常接续——plan 制品已有，继续生成） |
+| started | proposal.md 不存在 | 重新进入 brainstorming（回溯后——以现有 draft.md 为基础重新讨论需求） |
+| planned | — | alloy-apply |
+| applied | — | alloy-archive |
+| archived | — | alloy-finish |
+| finished | — | 工作流已完成——如需继续修改，使用自然对话提交新变更 |
+
+**实现方式：** 根据 phase 值，输出对应命令文件的完整指令（`commands/alloy/plan.md` / `apply.md` / `archive.md` / `finish.md`），将 change name 和检测到的进度信息作为上下文传入。Agent 无缝进入对应阶段。
+
+一致性检查（双向）：
+- worktree 字段有值但磁盘路径不存在 → ⚠️ "worktree 残留：.alloy.yaml 声称有 worktree 但磁盘不存在"
+- worktree 字段为 null 但 `.worktrees/<name>/` 目录存在 → ⚠️ "worktree 孤儿：磁盘存在 worktree 但 .alloy.yaml 未记录，建议手动验证并更新状态"
+- 发现孤儿 worktree 时，询问用户是否修复 .alloy.yaml：`alloy _state write openspec/changes/<name> worktree ".worktrees/<name>"`
+
+---
+
+## 多选（有多个活跃 change）
+
+```
+┌──────────────────────────────────────┐
+│ Alloy [1/5] · Phase: Start           │
+│ 启动时间: 从 phase_timings.start.started_at 读取，若无则从 created_at 读取            │
+└──────────────────────────────────────┘
+
+→ 检测到 <N> 个活跃 change，请选择。
+```
+
+### [Step 1/1] 展示并选择
+
+列出所有活跃 change（名称 + phase + 制品状态），让用户选择接续哪个，或 `--new <topic>` 开新 change。