阶段 0：前置检查

先确认 CLI 可用：

bash

# Unix/macOS
openspec --version 2>&1 || echo "CLI_NOT_INSTALLED"
# Windows (PowerShell)
# if (Get-Command openspec -ErrorAction SilentlyContinue) { openspec --version } else { echo "CLI_NOT_INSTALLED" }

若未安装：提示用户先安装后再继续，停止流程。

阶段 1：欢迎与目标对齐

清晰说明本次目标：

•选择一个小而真实的任务
•走完一轮完整工件流转（proposal → specs → design → tasks）
•进入 apply 并完成实现
•最后归档 change

建议控制在 15~20 分钟，重点是“看懂工作流如何工作”。

阶段 2：挑选练习任务

在仓库中快速寻找 3~4 个“适合 onboarding 的小任务”，例如：

•TODO/FIXME/HACK
•明显缺失的错误处理
•可补的测试覆盖
•可替换的 any
•非必要调试输出

并给出每个候选项的：

•位置（文件路径）
•预估改动范围
•为什么适合首轮演示

若用户选的范围过大，先建议切片再做。

阶段 3：快速演示 explore

在正式建 change 前，先做 1~2 分钟探索：

•读取关键文件
•用简短分析说明现状
•必要时画一张 ASCII 小图

然后暂停，确认用户是否继续创建 change。

阶段 4：创建 change

•协助命名（kebab-case）
•执行：

bash

openspec new change "<name>"

如用户指定 schema，则添加 --schema <schema>。

•展示状态：

bash

openspec status --change "<name>"

解释当前 ready / blocked 工件。

阶段 5：逐步创建工件

按 status 中 ready 顺序推进。每个工件都执行：

bash

openspec instructions <artifact-id> --change "<name>"

然后：

•解释该工件目的
•起草内容（可让用户补充）
•写入对应文件
•更新状态并说明下一步

至少覆盖 proposal/specs/design/tasks（以 schema 为准）。

阶段 6：进入实现（apply）

执行：

bash

openspec instructions apply --change "<name>"

根据输出推进：

•blocked：先补齐缺失工件
•ready：按 tasks 执行实现
•all_done：进入归档准备

实现过程中保持“轻讲解、重实操”。

阶段 7：归档收尾

确认任务完成后，执行归档流程并解释归档结果。

最后给出简短 recap：

•今天走过了哪些阶段
•关键命令有哪些
•后续可独立使用哪些入口（/opsx:new、/opsx:ff、/opsx:continue、/opsx:apply、/opsx:archive）

护栏

•不要跳阶段（onboarding 目标是让用户看到完整闭环）
•每个关键切换点都做短暂停顿确认
•不要为了“讲完流程”牺牲真实任务质量
•用户想中途退出时，礼貌收尾并给出下次继续的最短路径