SuperAPI AI 工具集

openspec-onboard

编程与开发

查看项目

更新于 10-22 09:57

技能介绍

openspec-onboard 是一个用于 OpenSpec 的引导式入门技能,目标是在真实代码库中边做边讲,带用户完成第一次完整的 OpenSpec 工作流循环。

用途 它面向首次使用 OpenSpec 的开发者,用一个小而真实的任务演示从想法到实现的完整变更周期,帮助理解 OpenSpec 的变更容器、提案、规格、设计、任务和归档等概念。

主要能力

  1. 预检:运行 openspec status --json 检查项目是否已初始化 OpenSpec;若未初始化,提示先执行 openspec init,并停止后续流程。
  2. 任务选择:扫描代码库中的小型改进点,包括 TODO/FIXME/HACK/XXX 注释、吞掉错误的 catch、缺少测试的函数、TypeScript 中的 any、调试残留(console.log、debugger)、缺少输入校验等,并结合 git log 近期活动,给出 3 到 4 个具体建议;若未发现合适任务,则询问用户想做什么。
  3. 范围护栏:当用户选择的任务过大时,建议拆小、换任务或坚持继续(软性限制,尊重用户选择)。
  4. 探索演示:简要阅读相关文件、必要时画 ASCII 示意图、说明注意事项,演示 explore 模式的思考方式。
  5. 创建变更:用 openspec new change 生成 kebab-case 命名的变更目录,展示 proposal.md、design.md、specs/、tasks.md 的结构。
  6. 逐步产出工件:依次撰写提案(为什么做、改什么、能力、影响)、规格(ADDED Requirements 与 WHEN/THEN/AND 场景)、设计(上下文、目标/非目标、决策)、任务(带复选框的实施清单),并在关键节点暂停等待用户确认。
  7. 实施与归档:逐项实现任务并在 tasks.md 中勾选,最后用 openspec archive 将变更移动到 archive/YYYY-MM-DD-<name>/ 保留决策记录。
  8. 复盘与命令参考:总结完整循环,并列出 /opsx-explore、/opsx-new、/opsx-ff、/opsx-continue、/opsx-apply、/opsx-verify、/opsx-archive 等命令的用途。
  9. 优雅退出:用户中途想停止时,说明变更已保存在 openspec/changes/<name>/,之后可用 /opsx-continue 或 /opsx-apply 继续;若用户只想看命令,则直接给出速查表。

使用方式 在已初始化 OpenSpec 的项目中启动该引导流程,按提示选择任务并逐步确认。流程在探索后、提案草稿后、任务生成后、归档后等关键节点暂停,采用解释、执行、展示、暂停的节奏推进。

适用场景 适合 OpenSpec 新手学习完整工作流、团队统一变更管理流程、以及用一个真实小任务快速熟悉提案到归档的各环节。

限制 需要项目已初始化 OpenSpec,否则流程会停止;示例任务应为小型改动,大型功能会被建议拆分;实施阶段以轻量讲解为主,不逐行解释代码。

分类:编程与开发