openspec-onboard

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

存储选择： 如果用户指定了存储（存储是指在这台机器上注册的独立 OpenSpec 仓库），或者相关工作位于某个存储中，运行 openspec store list --json 以发现已注册的存储 ID，然后在读取或写入规范和变更的命令（new change、status、instructions、list、show、validate、archive、doctor、context、schemas、view）中传入 --store <id>。选定后，在工作流剩余部分始终使用 --store <id>。以下命令示例中未指定存储的形式都只是简写：运行前请附加该标志。例如，运行 openspec status --change "<name>" --json --store "<id>"，而不是下面显示的未指定存储形式。其他命令不接受此标志。命令打印的提示中已包含该标志；后续命令也要保留它。如果未指定存储，命令会作用于最近的本地 openspec/ 根目录。

项目检查： 以下步骤要求项目已经在使用 OpenSpec。在第一个会写入内容的步骤（new change、archive、sync specs 或编写制品文件）之前，确认项目具有根目录：运行 openspec list --json（如果已选定存储，则传入 --store <id>，因为此时该存储就是根目录）并读取 root。存在根目录对象表示项目已完成设置。"root": null 表示尚未设置——此处没有 openspec/ 目录，而诸如 openspec new change 的写入操作会产生副作用并创建该目录。该命令也会以非零状态码退出；这是预期结果，而不是 CLI 故障，因此应读取 JSON，不要重试或绕过。

有一种情况中，"root": null 并不表示项目未设置：当 status 错误消息以 Declared in 或 Invalid store declaration in 开头，并指出此项目的 openspec/config.yaml（或 config.yml）时，说明项目通过其声明的存储使用 OpenSpec，但这台机器无法解析该存储（该存储尚未注册，或 store: 行格式错误）。不要将其视为未初始化，也不要继续以下分支：写入前先停止，并向用户展示该错误的 message 和 fix。

否则，如果没有根目录，接下来该怎么做取决于进入此工作流的方式：

• 自动选择： 这是你自行选择的工作流，用户没有提及 OpenSpec、没有提及此技能，也没有运行其斜杠命令。停止使用 OpenSpec，像没有安装 OpenSpec 一样正常回复用户的请求。不要要求他们进行任何设置，也不要提及 OpenSpec 设置。
• 明确请求使用 OpenSpec： 用户提到了 OpenSpec、提到了此技能，或运行了它的斜杠命令。写入前先停止，并询问如何继续：设置此项目（openspec init）、指定他们已有的存储（--store <id>），或针对这项请求继续使用 OpenSpec 之外的方式。等待他们答复。

在这两种情况下，都绝不要通过副作用创建根目录：除非用户要求，否则不要运行 openspec init；不要手动创建 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。请先安装，然后再返回 /openspec-onboard。

如果未安装，请在此处停止。

---

阶段 1：欢迎

显示：

## Welcome to OpenSpec!

I'll walk you through a complete change cycle—from idea to implementation—using a real task in your codebase. Along the way, you'll learn the workflow by doing it.

**What we'll do:**
1. Pick a small, real task in your codebase
2. Explore the problem briefly
3. Create a change (the container for our work)
4. Build the artifacts: proposal → specs → design → tasks
5. Implement the tasks
6. Archive the completed change

**Time:** ~15-20 minutes

Let's start by finding something to work on.

---

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

# 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 条具体建议：

## Task Suggestions

Based on scanning your codebase, here are some good starter tasks:

**1. [Most promising task]**
   Location: `src/path/to/file.ts:42`
   Scope: ~1-2 files, ~20-30 lines
   Why it's good: [brief reason]

**2. [Second task]**
   Location: `src/another/file.ts`
   Scope: ~1 file, ~15 lines
   Why it's good: [brief reason]

**3. [Third task]**
   Location: [location]
   Scope: [estimate]
   Why it's good: [brief reason]

**4. Something else?**
   Tell me what you'd like to work on.

Which task interests you? (Pick a number or describe your own)

如果没有发现问题： 则改为询问用户想构建什么：

我没有在你的代码库中发现明显的快速改进机会。你最近想添加或修复什么小功能？

范围护栏

如果用户选择或描述的任务过于庞大（大型功能、多日工作）：

That's a valuable task, but it's probably larger than ideal for your first OpenSpec run-through.

For learning the workflow, smaller is better—it lets you see the full cycle without getting stuck in implementation details.

**Options:**
1. **Slice it smaller** - What's the smallest useful piece of [their task]? Maybe just [specific slice]?
2. **Pick something else** - One of the other suggestions, or a different small task?
3. **Do it anyway** - If you really want to tackle this, we can. Just know it'll take longer.

What would you prefer?

如果用户坚持，可以让其覆盖此限制——这只是一个软性护栏。

---

第 3 阶段：探索演示

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

Before we create a change, let me quickly show you **explore mode**—it's how you think through problems before committing to a direction.

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

• 阅读涉及的文件
• 如果有帮助，绘制一个简要的 ASCII 图
• 说明需要考虑的事项

## Quick Exploration

[Your brief analysis—what you found, any considerations]

┌─────────────────────────────────────────┐
│   [Optional: ASCII diagram if helpful]  │
└─────────────────────────────────────────┘

Explore mode (`/openspec-explore`) is for this kind of thinking—investigating before implementing. You can use it anytime you need to think through a problem.

Now let's create a change to hold our work.

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

---

第 4 阶段：创建变更

说明：

## Creating a Change

A "change" in OpenSpec is a container for all the thinking and planning around a piece of work. It lives at the `changeRoot` reported by `openspec status --change "<name>" --json` and holds your artifacts—proposal, specs, design, tasks.

Let me create one for our task.

执行： 使用派生出的 kebab-case 名称创建变更：

openspec new change "<derived-name>"

展示：

Created: <changeRoot from status JSON>

The folder structure:

/ ├── proposal.md ← 变更原因（空文件，稍后填写） ├── design.md ← 实现方式（空文件） ├── specs/ ← 详细需求（空目录） └── tasks.md ← 实施清单（空文件）

Now let's fill in the first artifact—the proposal.

---

第 5 阶段：提案

说明：

## The Proposal

The proposal captures **why** we're making this change and **what** it involves at a high level. It's the "elevator pitch" for the work.

I'll draft one based on our task.

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

<capability-path> 是相对于 specs/ 的规范目录（例如， user-auth 或 identity/user-auth）。修改现有功能时，使用其准确路径。 对于新功能，遵循项目既有的规范组织方式。

Here's a draft proposal:

---

# Proposal

## Why

[1-2 sentences explaining the problem/opportunity]

## What Changes

[Bullet points of what will be different]

## Capabilities

### New Capabilities
- `<capability-path>`: [brief description]

### Modified Capabilities

- `<existing-capability-path>`: [brief description]

## Impact

- `src/path/to/file.ts`: [what changes]
- [other files if applicable]

---

Does this capture the intent? I can adjust before we save it.

暂停——等待用户批准或反馈。

获得批准后，保存提案：

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

然后将内容写入通过 openspec instructions proposal --change "<name>" --json 获取的 resolvedOutputPath。

Proposal saved. This is your "why" document—you can always come back and refine it as understanding evolves.

Next up: specs.

---

第 6 阶段：规范

说明：

## Specs

Specs define **what** we're building in precise, testable terms. They use a requirement/scenario format that makes expected behavior crystal clear.

For a small task like this, we might only need one spec file.

执行： 确定应创建规范文件的位置：

openspec instructions specs --change "<name>" --json
# Use resolvedOutputPath from the JSON. If it is a glob, choose the concrete file path using the schema instruction and the change's context.

起草规范内容：

Here's the spec:

---

# Spec Delta

## ADDED Requirements

### Requirement: <Name>

<Description of what the system should do>

#### Scenario: <Scenario name>

- **WHEN** <trigger condition>
- **THEN** <expected outcome>
- **AND** <additional outcome if needed>

---

This format—WHEN/THEN/AND—makes requirements testable. You can literally read them as test cases.

保存到从 resolvedOutputPath 中选定的具体文件路径。

---

第 7 阶段：设计

说明：

## Design

The design captures **how** we'll build it—technical decisions, tradeoffs, approach.

For small changes, this might be brief. That's fine—not every change needs deep design discussion.

执行： 起草 design.md：

Here's the design:

---

# Design

## Context

[Brief context about the current state]

## Goals / Non-Goals

**Goals:**
- [What we're trying to achieve]

**Non-Goals:**
- [What's explicitly out of scope]

## Decisions

### Decision 1: [Key decision]

[Explanation of approach and rationale]

---

For a small task, this captures the key decisions without over-engineering.

保存到通过 openspec instructions design --change "<name>" --json 获取的 resolvedOutputPath。

---

第 8 阶段：任务

说明：

## Tasks

Finally, we break the work into implementation tasks—checkboxes that drive the apply phase.

These should be small, clear, and in logical order. Each group carries the tests and documentation for its own work - the last group is only for integration checks.

执行： 根据规范和设计生成任务：

Here are the implementation tasks:

---

# Tasks

## 1. [Category or file]

- [ ] 1.1 [Specific task] — verify: [test, command, observable behavior, or delivered artifact]
- [ ] 1.2 [Specific task] — verify: [test, command, observable behavior, or delivered artifact]

## 2. Integration Verification

- [ ] 2.1 Verify [broader integration or system behavior] with [end-to-end test or observable result]

---

Each checkbox becomes a unit of work in the apply phase. Does this task breakdown look right?

暂停——等待用户批准或反馈。

获得批准后，保存到通过 openspec instructions tasks --change "<name>" --json 获取的 resolvedOutputPath。

然后询问：

“任务已保存。准备开始实施了吗？”

暂停——等待用户确认后再开始实施。

---

第 9 阶段：应用（实施）

说明：

## Implementation

Now we implement each task, checking them off as we go. I'll announce each one and occasionally note how the specs/design informed the approach.

执行： 对每项任务：

1. 宣布：“正在处理任务 N：[描述]”
2. 在代码库中实施变更
3. 自然地引用规范/设计：“规范中写明了 X，所以我会执行 Y”
4. 在 tasks.md 中标记完成：- [ ] → - [x]
5. 简要报告状态：“✓ 任务 N 已完成”

叙述保持简洁——不必逐行过度解释代码。

所有任务完成后：

## Implementation Complete

All tasks done:
- [x] Task 1
- [x] Task 2
- [x] ...

The change is implemented! One more step—let's archive it.

---

第 10 阶段：归档

说明：

## Archiving

When a change is complete, we archive it. The archive path is derived from `planningHome.changesDir` and the date.

Archived changes become your project's decision history—you can always find them later to understand why something was built a certain way.

执行： 归档变更（--yes 会自动确认提示，你无法通过工具调用回答这些提示）：

openspec archive "<name>" --yes

展示：

Archived to: `<planningHome.changesDir>/archive/<target-name>/` (the target name prepends today's date, unless the name already starts with a `YYYY-MM-DD-` prefix — then it is kept as-is, no second date)

The change is now part of your project's history. The code is in your codebase, the decision record is preserved.

---

第 11 阶段：回顾与后续步骤

## Congratulations!

You just completed a full OpenSpec cycle:

1. **Explore** - Thought through the problem
2. **New** - Created a change container
3. **Proposal** - Captured WHY
4. **Specs** - Defined WHAT in detail
5. **Design** - Decided HOW
6. **Tasks** - Broke it into steps
7. **Apply** - Implemented the work
8. **Archive** - Preserved the record

This same rhythm works for any size change—a small fix or a major feature.

---

## Command Reference

**The commands you have installed:**

 | Command          | What it does                               |
 |------------------|--------------------------------------------|
 | `/openspec-propose` | Create a change and generate all artifacts |
 | `/openspec-explore` | Think through problems before/during work  |
 | `/openspec-apply-change`   | Implement tasks from a change              |
 | `/openspec-archive-change` | Archive a completed change                 |
 | `/openspec-new-change`     | Start a new change, one artifact at a time |
 | `/openspec-continue-change` | Continue working on an existing change    |
 | `/openspec-ff-change`      | Fast-forward: create all artifacts at once |
 | `/openspec-verify-change`  | Verify implementation matches artifacts    |

---

## What's Next?

Try `/openspec-propose` on something you actually want to build. You've got the rhythm now!

---

平稳退出处理

用户想中途停止

如果用户表示需要停止、想暂停，或看起来不想继续：

No problem! Your change is saved at the `changeRoot` reported by `openspec status --change "<name>" --json`.

To pick up where we left off later, `openspec status --change "<name>" --json` shows exactly where the change stands.
- `/openspec-continue-change <name>` - Resume artifact creation
- `/openspec-apply-change <name>` - Jump to implementation (if tasks exist)

The work won't be lost. Come back whenever you're ready.

从容结束，不要施加压力。

用户只想查看命令参考

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

## OpenSpec Quick Reference

**The commands you have installed:**

 | Command                  | What it does                               |
 |--------------------------|--------------------------------------------|
 | `/openspec-propose <name>`  | Create a change and generate all artifacts |
 | `/openspec-explore`         | Think through problems (no code changes)   |
 | `/openspec-apply-change <name>`    | Implement tasks                            |
 | `/openspec-archive-change <name>`  | Archive when done                          |
 | `/openspec-new-change <name>`      | Start a new change, step by step           |
 | `/openspec-continue-change <name>` | Continue an existing change                |
 | `/openspec-ff-change <name>`       | Fast-forward: all artifacts at once        |
 | `/openspec-verify-change <name>`   | Verify implementation                      |

Try `/openspec-propose` to start your first change.

从容结束。

---

注意事项

• 在关键转换节点（探索之后、提案草稿之后、任务之后、归档之后）遵循 EXPLAIN → DO → SHOW → PAUSE 模式
• 实施过程中保持讲解简明——教学时不要说教
• 即使改动很小，也不要跳过阶段——目标是教授工作流
• 在标记的节点暂停以等待确认，但不要暂停过于频繁
• 妥善处理退出——绝不要施压让用户继续
• 使用真实的代码库任务——不要模拟，也不要使用虚假示例
• 适当引导用户缩小范围，但尊重用户的选择