首次使用 OpenSpec 或用户要求引导式入门时…

当用户想学习 OpenSpec 的完整变更周期，或明确要求 openspec onboard / opsx onboard 时，用真实小任务边做边教。

适用场景

解决思路

1. 若用户指定了某个 store，或工作本身位于某个 store 中，先运行 `openspec store list --json` 发现已注册的 store id，再在读写 spec 与 change 的命令上附加 `--store <id>`：`new change`、`status`、`instructions`、`list`、`show`、`validate`、`archive`、`doctor`、`context`、`schemas`、`view`。
2. 选定 store 后，在整个工作流中把 `--store <id>` 当作粘性参数：每次运行上述命令前都追加该 flag，例如运行 `openspec status --change "<name>" --json --store "<id>"`，而不是不带 flag 的形式；其他命令不接受该 flag；命令打印的提示已经带上该 flag，后续继续保留。
3. 没有 store 时，这些命令作用于最近的本地 `openspec/` 根。
4. 在第一个写操作（`new change`、`archive`、`sync specs` 或编写 artifact 文件）之前，运行 `openspec list --json`（已选 store 时加上 `--store <id>`）并读取 `root`：有 root 对象表示项目已配置；`"root": null` 表示未配置，写入会副作用创建 `openspec/`，命令非零退出是这个答案而不是 CLI 损坏，应读 JSON 而不是重试或绕过。
5. 若 `status` 的错误信息以 `Declared in` 或 `Invalid store declaration in` 开头，并指名本项目的 `openspec/config.yaml`（或 `config.yml`），说明项目通过本机无法解析的 store 使用 OpenSpec（store 未注册或 `store:` 行格式错误）；不要把它当作未初始化并跳过后续分支，应在写入前停下，向用户展示该错误的 `message` 和 `fix`。
6. 无 root 且工作流是自己自动选择时（用户没有命名 OpenSpec、没有命名本技能、也没有运行其 slash 命令），停止使用 OpenSpec，像没有安装 OpenSpec 一样正常回答请求；不要要求用户做任何配置，也不要提 OpenSpec 配置。
7. 无 root 且是显式 OpenSpec 请求时（用户命名了 OpenSpec、命名了本技能或运行了其 slash 命令），在写入前停下并询问如何继续：用 `openspec init` 配置本项目、用 `--store <id>` 指向已有 store、或本次请求不用 OpenSpec 继续；等待用户回答。
8. 以上两种无 root 分支下都绝不要副作用创建 root：用户没要求就不要运行 `openspec init`，不要手工创建 `openspec/` 文件，也不要让任何命令创建它。
9. Preflight：运行 `openspec --version 2>&1 || echo "CLI_NOT_INSTALLED"`（Windows 用对应 PowerShell 命令）检查 OpenSpec CLI 是否安装；若未安装，提示先安装 OpenSpec CLI 再回来运行 `/openspec-onboard`，并在此停止。
10. Phase 1：显示欢迎信息，说明将用真实任务走完从想法到实现的完整变更周期，列出将要做的步骤（选小任务、探索问题、创建 change、构建 proposal → specs → design → tasks、实现、归档），并说明约需 15-20 分钟。
11. Phase 2：扫描代码库寻找小改进机会，包括搜索 `TODO`、`FIXME`、`HACK`、`XXX` 注释；吞掉错误的 `catch` 块或没有 try-catch 的风险操作；`src/` 中没有测试的函数；TypeScript 中的 `: any`、`as any`；非调试代码中的 `console.log`、`console.debug`、`debugger`；没有校验的用户输入处理。
12. 检查最近的 git 活动：运行 `git log --oneline -10`（Windows 用对应命令），没有 git 历史时回退到提示信息。
13. 从分析结果中给出 3-4 个具体任务建议，每条包含位置（如 `src/path/to/file.ts:42`）、范围（约几个文件、多少行）和为什么适合作为入门任务，并提供「其他」选项让用户描述自己的任务；询问用户选哪一个。
14. 若没有发现明显机会，回退为询问用户：有什么一直想添加或修复的小东西。
15. 范围护栏：若用户选的任务过大（大功能、多日工作），说明首次跑通工作流更适合小任务，并给出三个选项：把它切成最小有用片段、换一个其他建议或小任务、坚持做但会花更久；用户坚持时允许覆盖，这是软护栏。
16. Phase 3：任务选定后演示 explore mode，花 1-2 分钟调查相关代码（读取涉及的文件、必要时画 ASCII 图、记录注意事项），并说明 `/openspec-explore` 用于实现前的思考、可随时使用；随后暂停等待用户确认再继续。
17. Phase 4：解释 change 是容纳某项工作全部思考和计划的容器，位于 `openspec status --change "<name>" --json` 报告的 `changeRoot`；用派生出的 kebab-case 名称运行 `openspec new change "<derived-name>"`，并展示 changeRoot 及目录结构（`proposal.md`、`design.md`、`specs/`、`tasks.md`）。
18. Phase 5：解释 proposal 捕获为什么做（why）和高层做什么（what）；先草拟 proposal 但不要保存，说明 `<capability-path>` 是相对 `specs/` 的 spec 目录（例如 `user-auth` 或 `identity/user-auth`），修改现有能力要用现有精确路径，新增能力要遵循项目既有 spec 组织方式；草稿包含 Why、What Changes、Capabilities（New Capabilities / Modified Capabilities）、Impact；暂停等待用户批准或反馈。
19. Phase 5 批准后：运行 `openspec instructions proposal --change "<name>" --json`，把内容写入返回的 `resolvedOutputPath`。
20. Phase 6：解释 specs 用 requirement/scenario 格式精确、可测试地定义做什么（what）；运行 `openspec instructions specs --change "<name>" --json` 并使用其 `resolvedOutputPath`，若它是 glob，则依据 schema instruction 和 change 上下文选择具体文件路径；草拟 spec delta，包含 `## ADDED Requirements`、`### Requirement:`、`#### Scenario:` 以及 `WHEN`/`THEN`/`AND`；保存到选定的具体文件路径。
21. Phase 7：解释 design 捕获怎么做（how），即技术决策、权衡和方案；草拟 `design.md`，包含 Context、Goals / Non-Goals、Decisions（每个关键决策及理由）；保存到 `openspec instructions design --change "<name>" --json` 返回的 `resolvedOutputPath`。
22. Phase 8：解释 tasks 是把工作拆成驱动 apply 阶段的复选框；根据 specs 和 design 生成 tasks，每条写成 `- [ ] 1.1 [具体任务] — verify: [测试、命令、可观察行为或交付物]`，并包含 `## 2. Integration Verification` 及一条端到端或系统级验证项；暂停等待用户批准或反馈。
23. Phase 8 批准后：保存到 `openspec instructions tasks --change "<name>" --json` 返回的 `resolvedOutputPath`，然后询问是否准备好实现，并再次暂停等待确认。
24. Phase 9：对每个任务依次执行——宣布「Working on task N: [description]」；在代码库中实现变更；自然引用 specs/design 说明依据（如「spec 说 X，所以我做 Y」）；在 `tasks.md` 中把 `- [ ]` 改为 `- [x]`；简短报告「✓ Task N complete」；保持叙述轻量，不要逐行解释代码；全部完成后汇总已完成任务并说明下一步是归档。
25. Phase 10：解释归档是把完成的 change 保存为项目决策历史；运行 `openspec archive "<name>" --yes`（`--yes` 用于回答工具调用无法回答的确认提示）；展示归档路径为 `<planningHome.changesDir>/archive/<target-name>/`，目标名会前置今天日期，除非名字已以 `YYYY-MM-DD-` 开头则原样保留。
26. Phase 11：回顾完整 cycle 的 8 步（Explore、New、Proposal、Specs、Design、Tasks、Apply、Archive），说明同样节奏适用于任意大小的变更，展示已安装命令参考表，并建议用 `/openspec-propose` 在真正想构建的东西上开始。
27. 中途停止处理：若用户想停止、暂停或显得不投入，告知 change 保存在 `openspec status --change "<name>" --json` 报告的 `changeRoot`，用同一命令可查看进度，用 `/openspec-continue-change <name>` 恢复 artifact 创建，用 `/openspec-apply-change <name>` 跳到实现（若有 tasks），无压力地优雅退出。
28. 只要命令参考的处理：若用户说只想看命令或跳过教程，展示 OpenSpec 快速参考表（`/openspec-propose <name>`、`/openspec-explore`、`/openspec-apply-change <name>`、`/openspec-archive-change <name>`、`/openspec-new-change <name>`、`/openspec-continue-change <name>`、`/openspec-ff-change <name>`、`/openspec-verify-change <name>`），建议用 `/openspec-propose` 开始，然后优雅退出。
29. 全程遵循 EXPLAIN → DO → SHOW → PAUSE 模式，在关键转换点（explore 之后、proposal 草稿之后、tasks 之后、archive 之后）执行。
30. 实现期间保持叙述轻量，教学但不说教。
31. 即使变更很小也不要跳过任何阶段，目标是教学完整工作流。
32. 在标记点暂停等待确认，但不要过度暂停。
33. 优雅处理退出，绝不给用户施压继续。
34. 使用真实的代码库任务，不要模拟或使用假例子。
35. 温和调整范围，引导用户选择更小任务，但尊重用户选择。

适用边界 · 注意事项

• 需要先安装 openspec CLI；未安装时应提示安装并停止，无法执行此工作流。
• 项目未初始化且用户并未显式要求 OpenSpec 时，不要强行引导或擅自运行 openspec init 创建根目录。
• 用户只想要普通编码帮助、并不想学习 OpenSpec 工作流时，不应套用这套引导流程。