用途:这是 OpenSpec 的引导式入门(onboarding)技能,面向首次使用 OpenSpec 的用户,在真实代码库中完成一次完整工作流循环,边操作边讲解。
主要能力与流程:先做预检,用 openspec --version 确认 CLI 已安装,未安装则停止并提示先安装。随后依次进行:欢迎说明;扫描代码库(TODO/FIXME、缺失错误处理、无测试函数、any 类型、调试残留、缺失校验)并给出 3-4 个小型任务建议,任务过大时给出缩小范围等软性护栏;演示 explore 模式做简短调研;用 openspec new change "<derived-name>" 创建变更容器;依次编写 proposal、specs、design、tasks 四类产物,每步先草拟、经用户确认后再保存;按任务实现代码并勾选 tasks.md;最后用 openspec archive "<name>" --yes 归档,并给出命令速查与后续建议。
使用方式:涉及规格与变更的读写命令(new change、status、instructions、list、show、validate、archive、doctor、context、schemas、view)在选定 store 后需附加 --store <id>,该标志在后续步骤中保持有效;未选 store 时作用于最近的本地 openspec/ 根目录。写操作前先用 openspec list --json 读取 root 判断项目是否已初始化;"root": null 表示未初始化,命令会以非零退出,应读取 JSON 而非重试。产物保存路径取自 openspec instructions <artifact> --change "<name>" --json 返回的 resolvedOutputPath。
适用场景:希望学习 OpenSpec 完整变更周期、需要有人带做一遍真实小任务的开发者。
限制:要求项目已使用 OpenSpec;未初始化时不得擅自运行 openspec init 或手工创建 openspec/ 文件,需先询问用户。若状态错误提示 Declared in 或 Invalid store declaration 并指向本项目 config.yaml,说明 store 声明无法解析,应停止写入并展示错误。用户中途退出时变更已保存,可用 openspec status 查看进度并继续。具体收费、平台支持等信息暂未提供。