openspec-onboard

---
name: openspec-onboard
description: OpenSpec 引导式入门 - 通过讲解和真实代码库工作走完一个完整的工作流周期。也在用户说 "openspec onboard" 或 "opsx onboard" 时使用。
allowed-tools: Bash(openspec-cn:*)
license: MIT
compatibility: 需要 openspec-cn CLI。
metadata:
  author: openspec
  version: "1.0"
---

引导用户完成他们的第一个完整 OpenSpec 工作流周期。这是一次教学体验——你将在他们的代码库中做真实工作，同时解释每一步。

**存储选择：** 若用户指定了一个存储（存储是注册在本机上的独立 OpenSpec 仓库）或工作位于某个存储中，请运行 `openspec-cn store list --json` 发现已注册的存储 ID，然后在读写 spec 和变更的命令上传递 `--store <id>`（`new change`、`status`、`instructions`、`list`、`show`、`validate`、`archive`、`doctor`、`context`、`schemas`、`view`）。选定后，将 `--store <id>` 视为在当前工作流其余部分中固定不变。以下每个未限定范围的命令示例均为简写形式：运行前请追加该标志。例如，运行 `openspec-cn status --change "<name>" --json --store "<id>"`，而非下面展示的未限定形式。其他命令不接受此标志。命令输出的提示已包含该标志；在后续操作中请保留它。若不指定存储，命令将对最近的本地 `openspec/` 根目录生效。

**项目检查：** 以下步骤期望项目已经在使用 OpenSpec。在第一个会写入任何内容的步骤之前（`new change`、`archive`、`sync specs`，或撰写任何产出物文件），确认项目已有根目录：运行 `openspec-cn list --json`（当选择了 store 时加上 `--store <id>`，因为此时 store 就是根目录），并读取 `root`。root 是一个对象表示项目已配置好。`"root": null` 表示尚未配置 —— 这里没有 `openspec/` 目录，而像 `openspec-cn new change` 这样的写入操作会作为副作用创建它。该命令还会以非零状态退出，这是它给出的答案而不是 CLI 坏了，因此请读取 JSON，不要重试或绕过它。

有一种 `"root": null` 与配置无关：当某条 `status` 错误消息以 `中声明` 或 `中的 store 声明无效` 结尾，并指向本项目的 `openspec/config.yaml`（或 `config.yml`）时，说明本项目确实通过它声明的某个 store 在使用 OpenSpec，只是本机无法解析该 store（store 未注册，或 `store:` 行格式有误）。不要把它当作未初始化而跳过下面的分支：请在写入前停下，把该错误的 `message` 和 `fix` 展示给用户。

否则，在没有根目录的情况下，接下来怎么做取决于这个工作流是如何被触发的：

- **自动选用**：这个工作流是你自己选的，用户没有提到 OpenSpec、没有点名这个 skill，也没有运行它的斜杠命令。停止使用 OpenSpec，按平常方式回答请求，就像没安装 OpenSpec 一样。不要要求他们做任何配置，也不要提及 OpenSpec 配置。
- **明确要求 OpenSpec**：用户提到了 OpenSpec、点名了这个 skill，或运行了它的斜杠命令。在写入前停下并询问如何继续：为本项目做配置（`openspec-cn init`）、指向他们已有的某个 store（`--store <id>`），还是本次请求不使用 OpenSpec 继续。等待他们的答复。

无论走哪个分支，都绝不能把创建根目录当作副作用：在用户要求之前不要运行 `openspec-cn init`，不要手工创建 `openspec/` 文件，也不要让任何命令创建它。

---

## 预检

开始前，检查 OpenSpec CLI 是否已安装：

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

**若 CLI 未安装：**
> OpenSpec CLI 未安装。先安装它，然后回到 `/openspec-onboard`。

若未安装则在此停止。

---

## 阶段 1：欢迎

展示：

```
## 欢迎使用 OpenSpec！

我将带你走完一个完整的变更周期——从想法到实现——使用你代码库中的真实任务。在此过程中，你将通过实践学习工作流。

**我们将做什么：**
1. 在你的代码库中选一个小而真实的任务
2. 简要探索问题
3. 创建一个变更（我们工作的容器）
4. 构建产出物：proposal → specs → design → tasks
5. 实现任务
6. 归档已完成的变更

**时间：** 约 15-20 分钟

让我们从找点事做开始。
```

---

## 阶段 2：任务选择

### 代码库分析

扫描代码库寻找小的改进机会。寻找：

1. **TODO/FIXME 注释** - 在代码文件中搜索 `TODO`、`FIXME`、`HACK`、`XXX`
2. **缺失的错误处理** - 吞掉错误的 `catch` 块、没有 try-catch 的危险操作
3. **没有测试的函数** - 交叉引用 `src/` 与测试目录
4. **类型问题** - TypeScript 文件中的 `any` 类型（`: any`、`as any`）
5. **调试残留** - 非调试代码中的 `console.log`、`console.debug`、`debugger` 语句
6. **缺失的验证** - 没有验证的用户输入处理器

也检查最近的 git 活动：
```bash
# Unix/macOS
git log --oneline -10 2>/dev/null || echo "No git history"
# Windows (PowerShell)
# git log --oneline -10 2>$null; if ($LASTEXITCODE -ne 0) { echo "No git history" }
```

### 展示建议

从你的分析中，展示 3-4 个具体建议：

```
## 任务建议

基于扫描你的代码库，这里有一些不错的入门任务：

**1. [最有潜力的任务]**
   位置：`src/path/to/file.ts:42`
   范围：约 1-2 个文件，约 20-30 行
   为什么好：[简要原因]

**2. [第二个任务]**
   位置：`src/another/file.ts`
   范围：约 1 个文件，约 15 行
   为什么好：[简要原因]

**3. [第三个任务]**
   位置：[位置]
   范围：[估计]
   为什么好：[简要原因]

**4. 其他？**
   告诉我你想做什么。

哪个任务感兴趣？（选一个数字或描述你自己的）
```

**若什么都没找到：** 回退到询问用户想构建什么：
> 我没有在你的代码库中找到明显的速胜点。有什么你一直想添加或修复的小东西吗？

### 范围护栏

若用户选择或描述的东西太大（主要功能、多天工作）：

```
那是一个有价值的任务，但对于你的第一次 OpenSpec 体验来说可能比理想的要大。

为了学习工作流，越小越好——它能让你看到完整周期而不会陷入实现细节。

**选项：**
1. **切分得更小** - [他们的任务]中最小有用的部分是什么？也许只是 [具体切片]？
2. **选别的** - 其他建议之一，或不同的小任务？
3. **就做这个** - 如果你真的想处理这个，可以。只是知道会花更长时间。

你更倾向于哪个？
```

若用户坚持则让他们覆盖——这是软护栏。

---

## 阶段 3：探索演示

一旦选定了任务，简要演示探索模式：

```
在创建变更前，让我快速给你展示 **探索模式**——这是在承诺一个方向之前思考问题的方式。
```

花 1-2 分钟调查相关代码：
- 阅读涉及的文件
- 如果有帮助，画一个简单的 ASCII 图
- 记录任何注意事项

```
## 快速探索

[你的简要分析——你发现了什么，任何注意事项]

┌─────────────────────────────────────────┐
│   [可选：有帮助的 ASCII 图]            │
└─────────────────────────────────────────┘

探索模式（`/openspec-explore`）正是为这类思考准备的 —— 在实现之前先调研。任何时候需要把事情想清楚，都可以使用它。

现在让我们创建一个变更来承载我们的工作。
```

**暂停** - 等待用户确认后再继续。

---

## 阶段 4：创建变更

**解释：**
```
## 创建变更

OpenSpec 中的 "变更" 是围绕一项工作所有思考和规划的容器。它位于 `openspec-cn status --change "<name>" --json` 报告的 `changeRoot`，承载你的产出物——proposal、specs、design、tasks。

让我为我们的任务创建一个。
```

**做：** 用推导的 kebab-case 名称创建变更：
```bash
openspec-cn new change "<derived-name>"
```

**展示：**
```
已创建：<changeRoot from status JSON>

文件夹结构：
```
<changeRoot>/
├── proposal.md    ← 我们为什么做这个（空的，我们将填充）
├── design.md      ← 我们怎么构建（空的）
├── specs/         ← 详细需求（空的）
└── tasks.md       ← 实现清单（空的）
```

现在让我们填写第一个产出物——proposal。
```

---

## 阶段 5：Proposal

**解释：**
```
## Proposal

Proposal 捕获我们**为什么**做这个变更以及高层面上涉及**什么**。它是工作的"电梯演讲"。

我将基于我们的任务起草一个。
```

**做：** 起草 proposal 内容（先不保存）：

`<capability-path>` 是相对于 `specs/` 的 spec 目录（例如 `user-auth` 或 `identity/user-auth`）。对于已修改的 capability，使用确切的现有路径。对于新 capability，遵循项目既有的 spec 组织方式。

```
这是草稿 proposal：

---

# Proposal

## Why

[1-2 句话解释问题/机会]

## What Changes

[什么将不同的要点]

## Capabilities

### New Capabilities
- `<capability-path>`: [简要描述]

### Modified Capabilities
<!-- 若修改现有行为 -->
- `<existing-capability-path>`：[简要描述]

## Impact

- `src/path/to/file.ts`：[什么变化]
- [其他文件（如适用）]

---

这捕捉了意图吗？我可以在保存前调整。
```

**暂停** - 等待用户批准/反馈。

批准后，保存 proposal：
```bash
openspec-cn instructions proposal --change "<name>" --json
```
然后将内容写入 `openspec-cn instructions proposal --change "<name>" --json` 的 `resolvedOutputPath`。

```
Proposal 已保存。这是你的 "为什么" 文档——你可以随时回来随着理解演进完善它。

接下来：specs。
```

---

## 阶段 6：Specs

**解释：**
```
## Specs

Specs 以精确、可测试的术语定义我们正在构建**什么**。它们使用需求/场景格式，使预期行为清晰明了。

对于这样的小任务，我们可能只需要一个 spec 文件。
```

**做：** 解析 spec 文件应创建到哪里：
```bash
openspec-cn instructions specs --change "<name>" --json
# 使用 JSON 中的 resolvedOutputPath。若是 glob，使用 schema 指令和变更上下文选择具体文件路径。
```

起草 spec 内容：

```
这是 spec：

---

# Spec Delta

## ADDED Requirements

### Requirement: <Name>

<系统应做什么的描述>

#### Scenario: <场景名>

- **WHEN** <触发条件>
- **THEN** <预期结果>
- **AND** <如有其他结果>

---

这种格式——WHEN/THEN/AND——使需求可测试。你简直可以把它们当作测试用例来读。
```

保存到从 `resolvedOutputPath` 选择的具体文件路径。

---

## 阶段 7：Design

**解释：**
```
## Design

Design 捕获我们**怎么**构建它——技术决策、权衡、方法。

对于小变更，这可能很简短。那没关系——不是每个变更都需要深入的设计讨论。
```

**做：** 起草 design.md：

```
这是 design：

---

# Design

## Context

[关于当前状态的简要上下文]

## Goals / Non-Goals

**Goals:**
- [我们想实现的]

**Non-Goals:**
- [明确不在范围内的]

## Decisions

### Decision 1: [关键决策]

[方法和理由的解释]

---

对于小任务，这捕获了关键决策而没有过度设计。
```

保存到 `openspec-cn instructions design --change "<name>" --json` 的 `resolvedOutputPath`。

---

## 阶段 8：Tasks

**解释：**
```
## Tasks

最后，我们将工作分解为实现任务——驱动 apply 阶段的复选框。

这些应该小、清晰、逻辑顺序合理。每个任务组自带其工作所需的测试和文档 - 最后一个任务组只用于集成检查。
```

**做：** 基于 specs 和 design 生成 tasks：

```
这是实现任务：

---

# Tasks

## 1. [类别或文件]

- [ ] 1.1 [具体任务] — verify: [测试、命令、可观察行为或交付的产物]
- [ ] 1.2 [具体任务] — verify: [测试、命令、可观察行为或交付的产物]

## 2. 集成验证

- [ ] 2.1 使用[端到端测试或可观察结果]验证[更广泛的集成或系统行为]

---

每个复选框成为 apply 阶段的工作单元。这个任务拆分看起来合适吗？
```

**暂停** - 等待用户批准/反馈。

批准后，保存到 `openspec-cn instructions tasks --change "<name>" --json` 的 `resolvedOutputPath`。

然后询问：
> "任务已保存。准备好实现了吗？"

**暂停** - 在实现之前等待用户确认。

---

## 阶段 9：Apply（实现）

**解释：**
```
## 实现

现在我们实现每个任务，边做边勾选。我将宣布每个任务并偶尔说明 specs/design 如何影响了方法。
```

**做：** 对每个任务：

1. 宣布："正在处理任务 N：[描述]"
2. 在代码库中实现变更
3. 自然地引用 specs/design："Spec 说 X，所以我做 Y"
4. 在 tasks.md 中标记完成：`- [ ]` → `- [x]`
5. 简要状态："✓ 任务 N 完成"

保持讲解轻松——不要过度解释每一行代码。

所有任务后：

```
## 实现完成

所有任务完成：
- [x] 任务 1
- [x] 任务 2
- [x] ...

变更已实现！还有一步——让我们归档它。
```

---

## 阶段 10：归档

**解释：**
```
## 归档

变更完成后，我们归档它。归档路径从 `planningHome.changesDir` 和日期派生。

归档的变更成为你项目的决策历史——你随时可以稍后找到它们以理解某东西为什么那样构建。
```

**做：** 归档变更（`--yes` 回答确认提示，你无法从工具调用中回答）：
```bash
openspec-cn archive "<name>" --yes
```

**展示：**
```
已归档到：`<planningHome.changesDir>/archive/<target-name>/`（目标名称前面加上今天的日期，除非名称已以 `YYYY-MM-DD-` 前缀开头 — 则保持原样，不加第二个日期）

变更现在是你项目历史的一部分。代码在你的代码库中，决策记录已保存。
```

---

## 阶段 11：回顾与下一步

```
## 恭喜！

你刚完成了一个完整的 OpenSpec 周期：

1. **Explore** - 思考问题
2. **New** - 创建变更容器
3. **Proposal** - 捕获为什么
4. **Specs** - 详细定义什么
5. **Design** - 决定怎么做
6. **Tasks** - 分解为步骤
7. **Apply** - 实现工作
8. **Archive** - 保存记录

同样的节奏适用于任何大小的变更——小修复或主要功能。

---

## 命令参考

**你已安装的命令：**

 | 命令              | 作用                               |
 |-------------------|--------------------------------------------|
 | `/openspec-propose` | 创建一个变更并生成全部制品 |
 | `/openspec-explore` | 在动手前/动手过程中想清楚问题  |
 | `/openspec-apply-change`   | 实现变更中的任务              |
 | `/openspec-archive-change` | 归档已完成的变更                 |
 | `/openspec-new-change`     | 启动新变更，一次一个制品 |
 | `/openspec-continue-change` | 继续处理一个已有的变更    |
 | `/openspec-ff-change`      | 快进：一次性创建全部制品 |
 | `/openspec-verify-change`  | 验证实现是否与制品一致    |

---

## 接下来？

在你真正想构建的东西上试试 `/openspec-propose`。你现在已经找到节奏了！
```

---

## 优雅退出处理

### 用户想中途停止

若用户说需要停止、想暂停或似乎不投入：

```
没问题！你的变更保存在 `openspec-cn status --change "<name>" --json` 报告的 `changeRoot`。

稍后从我们停下的地方继续：`openspec-cn status --change "<name>" --json` 精确显示变更的当前状态。
- `/openspec-continue-change <name>` - 恢复制品创建
- `/openspec-apply-change <name>` - 跳转到实现（若任务已存在）

工作不会丢失。随时回来。
```

优雅退出，不要施压。

### 用户只想看命令参考

若用户说只想看命令或跳过教程：

```
## 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` 开始你的第一个变更。
```

优雅退出。

---

## 护栏

- **在关键转换处遵循 解释 → 做 → 展示 → 暂停 模式**（探索后、proposal 草稿后、tasks 后、归档后）
- **实现期间讲解保持轻松**——教导而不说教
- **不要跳过阶段**，即使变更很小——目标是教授工作流
- **在标记点暂停**等待确认，但不要过度暂停
- **优雅处理退出**——绝不施压用户继续
- **使用真实代码库任务**——不要模拟或使用虚假示例
- **温和调整范围**——引导向更小任务但尊重用户选择

More agent context in studyzy/OpenSpec-cn

16 other files this repository gives its agents.