用途
openspec-onboard 是一个面向 OpenSpec 新用户的引导式入门技能。它不是单纯讲解命令,而是在用户自己的代码库中完成一个真实的小型变更,通过“边做边学”帮助用户理解 OpenSpec 的完整工作流。官方说明将其定位为一次教学体验:在解释每个步骤的同时,在代码库中做实际工作。
主要能力
-
预检:在开始前执行
openspec status --json 2>&1 || echo "NOT_INITIALIZED"检查 OpenSpec 是否已初始化。若未初始化,会提示先运行openspec init,然后停止引导。 -
任务发现:扫描代码库寻找小型改进机会,包括 TODO/FIXME/HACK/XXX 注释、吞掉错误的 catch 块、缺少测试的函数、TypeScript 中的
: any/as any、非调试代码中的 console.log/console.debug/debugger、缺少输入校验的用户输入处理等;同时通过git log --oneline -10 2>/dev/null || echo "No git history"查看最近提交。 -
候选建议:基于扫描结果给出 3-4 个具体任务建议,标明位置、范围和推荐理由;若未找到明显机会,则询问用户想添加或修复什么小功能。
-
范围护栏:如果用户选择的任务过大(重大功能或多日工作),会软性建议切片变小、换一个任务,或尊重用户选择继续做大任务。
-
探索演示:用 1-2 分钟阅读相关文件、绘制简单 ASCII 示意图、记录注意事项,演示
/opsx:explore的“先想清楚再动手”模式。 -
创建变更:使用
openspec new change "<derived-name>"创建变更目录,并展示openspec/changes/<name>/下 proposal.md、design.md、specs/、tasks.md 的结构。 -
逐项构建工件:依次起草 proposal(为什么做、改什么、能力与影响)、specs(采用 Requirement + Scenario 的 WHEN/THEN/AND 可测试格式)、design(背景、目标/非目标、决策)、tasks(带复选框的实施清单)。每个关键节点会暂停等待用户确认或反馈。提案保存前会执行
openspec instructions proposal --change "<name>" --json。 -
实施:按任务清单逐项实施,在代码库中真实修改,自然引用 specs/design 说明依据,并将 tasks.md 中对应复选框从
- [ ]改为- [x],保持轻量讲解。 -
归档:执行
openspec archive "<name>",将变更移动到openspec/changes/archive/YYYY-MM-DD-<name>/,保留为项目决策历史。 -
收尾与命令参考:总结完整周期(Explore、New、Proposal、Specs、Design、Tasks、Apply、Archive),并提供
/opsx:explore、/opsx:new、/opsx:ff、/opsx:continue、/opsx:apply、/opsx:verify、/opsx:archive的命令速查表。 -
优雅退出:若用户中途想停止,会说明变更已保存在
openspec/changes/<name>/,之后可用/opsx:continue <name>继续创建工件,或用/opsx:apply <name>直接进入实施;若用户只想看命令,则直接给出速查表,不施压继续。
使用方式
该技能以引导流程运行,核心命令包括 openspec init、openspec status --json、openspec new change "<name>"、openspec instructions proposal --change "<name>" --json、openspec archive "<name>",以及 /opsx: 系列斜杠命令。流程遵循 EXPLAIN → DO → SHOW → PAUSE 的模式,在探索后、提案草稿后、任务清单后、归档后等关键转换点暂停等待确认,实施阶段保持轻量叙述,不跳过阶段,即便变更很小也完整走一遍以达成教学目的。
适用场景
适合刚接触 OpenSpec、希望用 15-20 分钟在真实代码库中体验从想法到实现完整周期的开发者;也适合团队新成员熟悉 OpenSpec 的工件结构与变更管理节奏。它强调使用真实代码库任务,不模拟或使用假例子。
限制
- 项目必须已执行
openspec init,否则引导会停止。 - 定位为入门教学,不替代完整文档;对大型任务仅提供软性范围建议。
- 资料未提供具体收费、平台支持范围或与其他工具的集成细节,暂未提供。