openspec-onboard

name	openspec-onboard
description	OpenSpec 引导式入门——通过叙述和真实代码库工作，完整走一遍工作流循环。
license	MIT
compatibility	Requires openspec CLI.
metadata	{"author":"openspec","version":"1.0","generatedBy":"1.2.0"}

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

---

预检

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

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

若 CLI 未安装：

OpenSpec CLI 未安装。请先安装，然后再回来使用 /opsx:onboard。

若未安装则停止。

---

第一阶段：欢迎

显示：

## 欢迎使用 OpenSpec！

我将引导您完成一个完整的变更循环——从想法到实现——在您的代码库中完成一个真实任务。在此过程中，您将通过实践学习工作流。

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

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

让我们先找点要做的事情。

---

第二阶段：任务选择

代码库分析

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

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 活动：

# Unix/macOS
git log --oneline -10 2>/dev/null || echo "无 git 历史"
# Windows (PowerShell)
# git log --oneline -10 2>$null; if ($LASTEXITCODE -ne 0) { echo "无 git 历史" }

展示建议

根据您的分析，提出 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. **就这个** - 若您真的想处理这个，也可以。只是会花更长时间。

您更倾向于哪种？

若用户坚持，可以继续——这是软性限制。

---

第三阶段：探索演示

选定任务后，简短演示探索模式：

在我们创建变更之前，让我快速展示**探索模式**——这是您在确定方向之前思考问题的方式。

花 1-2 分钟调查相关代码：

• 读取涉及的文件
• 若有帮助，画一个简短的 ASCII 图
• 记录任何注意事项

## 快速探索

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

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

探索模式（`/opsx:explore`）就是用于这种思考——在实现前先调查。您随时可以使用它来思考问题。

现在让我们创建一个变更来容纳我们的工作。

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

---

第四阶段：创建变更

讲解：

## 创建变更

OpenSpec 中的"变更"是围绕一块工作的所有思考和规划的容器。它存放在 `openspec/changes/<name>/` 中，保存您的 artifact——proposal、specs、design、tasks。

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

执行： 用推导出的 kebab-case 名称创建变更：

openspec new change "<derived-name>"

展示：

已创建：`openspec/changes/<name>/`

目录结构：

openspec/changes// ├── proposal.md ← 我们为什么要做这件事（空，我们来填） ├── design.md ← 我们如何构建它（空） ├── specs/ ← 详细需求（空） └── tasks.md ← 实现清单（空）

现在让我们填写第一个 artifact——proposal。

---

第五阶段：Proposal

讲解：

## Proposal

Proposal 记录我们**为什么**要进行此变更，以及它在高层面上涉及什么。这是工作的"电梯演讲"。

我将根据我们的任务起草一个。

执行： 起草 proposal 内容（暂不保存）：

这是一个 proposal 草稿：

---

## Why（为什么）

[1-2 句话说明问题/机会]

## What Changes（变更内容）

[将发生什么不同的要点]

## Capabilities（功能）

### New Capabilities（新功能）
- `<capability-name>`：[简短描述]

### Modified Capabilities（修改的功能）
<!-- 若修改现有行为 -->

## Impact（影响）

- `src/path/to/file.ts`：[变更内容]
- [其他文件，如适用]

---

这是否准确表达了意图？我可以在保存之前调整。

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

批准后保存 proposal：

openspec instructions proposal --change "<name>" --json

然后将内容写入 openspec/changes/<name>/proposal.md。

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

下一步：specs。

---

第六阶段：Specs

讲解：

## Specs

Spec 以精确、可测试的方式定义**我们在构建什么**。它们使用需求/场景格式，使预期行为一目了然。

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

执行： 创建 spec 文件：

# Unix/macOS
mkdir -p openspec/changes/<name>/specs/<capability-name>
# Windows (PowerShell)
# New-Item -ItemType Directory -Force -Path "openspec/changes/<name>/specs/<capability-name>"

起草 spec 内容：

这是 spec：

---

## ADDED Requirements

### Requirement: <名称>

<系统应做什么的描述>

#### Scenario: <场景名称>

- **WHEN** <触发条件>
- **THEN** <预期结果>
- **AND** <额外结果（如需要）>

---

这种格式——WHEN/THEN/AND——使需求可测试。您可以直接将它们读作测试用例。

保存到 openspec/changes/<name>/specs/<capability>/spec.md。

---

第七阶段：Design

讲解：

## Design

Design 记录**我们如何构建它**——技术决策、权衡、方案。

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

执行： 起草 design.md：

这是设计：

---

## Context（背景）

[关于当前状态的简短背景]

## Goals / Non-Goals（目标/非目标）

**目标：**
- [我们试图实现什么]

**非目标：**
- [明确排除在外的内容]

## Decisions（决策）

### 决策 1：[关键决策]

[方案说明和理由]

---

对于小任务，这记录了关键决策，而不过度设计。

保存到 openspec/changes/<name>/design.md。

---

第八阶段：Tasks

讲解：

## Tasks

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

这些应该小、清晰，并按逻辑顺序排列。

执行： 根据 spec 和 design 生成任务：

这是实现任务：

---

## 1. [类别或文件]

- [ ] 1.1 [具体任务]
- [ ] 1.2 [具体任务]

## 2. 验证

- [ ] 2.1 [验证步骤]

---

每个复选框在应用阶段成为一个工作单元。准备好实现了吗？

暂停 - 等待用户确认准备好实现。

保存到 openspec/changes/<name>/tasks.md。

---

第九阶段：应用（实现）

讲解：

## 实现

现在我们逐个实现任务，完成时打勾。我会声明每一个，偶尔说明 spec/design 如何指导了这个方案。

执行： 对每个任务：

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

保持叙述简洁——不要对每行代码过度解释。

所有任务完成后：

## 实现完成

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

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

---

第十阶段：归档

讲解：

## 归档

当变更完成时，我们归档它。这会将它从 `openspec/changes/` 移动到 `openspec/changes/archive/YYYY-MM-DD-<name>/`。

归档的变更成为项目的决策历史——您随时可以找到它们，了解某些东西为什么以特定方式构建。

执行：

openspec archive "<name>"

展示：

已归档到：`openspec/changes/archive/YYYY-MM-DD-<name>/`

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

---

第十一阶段：回顾与下一步

## 恭喜！

您刚刚完成了一个完整的 OpenSpec 循环：

1. **探索** - 思考了问题
2. **New** - 创建了变更容器
3. **Proposal** - 记录了为什么（WHY）
4. **Specs** - 详细定义了做什么（WHAT）
5. **Design** - 决定了如何做（HOW）
6. **Tasks** - 分解成了步骤
7. **Apply** - 实现了工作
8. **Archive** - 保存了记录

这个节奏适用于任何规模的变更——小修复或大功能。

---

## 命令参考

**核心工作流：**

| 命令 | 作用 |
|---------|--------------|
| `/opsx:propose` | 创建变更并生成所有 artifact |
| `/opsx:explore` | 在工作前/中思考问题 |
| `/opsx:apply` | 实现变更中的任务 |
| `/opsx:archive` | 完成后归档变更 |

**其他命令：**

| 命令 | 作用 |
|---------|--------------|
| `/opsx:new` | 启动新变更，逐步完成 artifact |
| `/opsx:continue` | 继续现有变更 |
| `/opsx:ff` | 快进：一次创建所有 artifact |
| `/opsx:verify` | 验证实现是否匹配 artifact |

---

## 下一步？

在您真正想构建的东西上试试 `/opsx:propose`。您已经掌握节奏了！

---

优雅退出处理

用户想要中途停止

若用户表示需要停止、想暂停或看起来不感兴趣：

没问题！您的变更已保存在 `openspec/changes/<name>/`。

稍后继续：
- `/opsx:continue <name>` - 继续创建 artifact
- `/opsx:apply <name>` - 直接跳到实现（若任务已存在）

工作不会丢失。准备好了随时回来。

优雅退出，不施加压力。

用户只想要命令参考

若用户表示只想查看命令或跳过教程：

## OpenSpec 快速参考

**核心工作流：**

| 命令 | 作用 |
|---------|--------------|
| `/opsx:propose <name>` | 创建变更并生成所有 artifact |
| `/opsx:explore` | 思考问题（不改代码） |
| `/opsx:apply <name>` | 实现任务 |
| `/opsx:archive <name>` | 完成后归档 |

**其他命令：**

| 命令 | 作用 |
|---------|--------------|
| `/opsx:new <name>` | 启动新变更，逐步操作 |
| `/opsx:continue <name>` | 继续现有变更 |
| `/opsx:ff <name>` | 快进：一次完成所有 artifact |
| `/opsx:verify <name>` | 验证实现 |

用 `/opsx:propose` 开始您的第一个变更。

优雅退出。

---

注意事项

• 遵循「讲解 → 执行 → 展示 → 暂停」模式，在关键过渡点（探索后、proposal 草稿后、任务后、归档后）
• 保持叙述简洁——在实现时教学，不说教
• 不要跳过阶段，即使变更很小——目标是教授工作流
• 在标记点等待确认，但不要过度暂停
• 优雅处理退出——不要施压让用户继续
• 使用真实代码库任务——不要模拟或使用假例子
• 温和地调整范围——引导向较小的任务，但尊重用户选择