Back to Details

openspec-onboard

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Guide the user through their first complete OpenSpec workflow cycle. This is a teaching experience—you'll do real work in their codebase while explaining each step.
引导用户完成他们的第一个完整OpenSpec工作流周期。这是一次教学体验——您将在他们的代码库中进行实际操作，同时讲解每一个步骤。

Preflight

前期检查

Before starting, check if OpenSpec is initialized:
bash
openspec status --json 2>&1 || echo "NOT_INITIALIZED"
If not initialized:
OpenSpec isn't set up in this project yet. Run 
openspec init
first, then come back to 
/opsx:onboard
.
Stop here if not initialized.
开始之前，请检查OpenSpec是否已初始化：
bash
openspec status --json 2>&1 || echo "NOT_INITIALIZED"
如果未初始化：
此项目中尚未设置OpenSpec。请先运行
openspec init
，然后再回到
/opsx:onboard
。
如果未初始化，请在此处停止。

Phase 1: Welcome

第一阶段：欢迎

Display:
undefined
显示以下内容：
undefined

Welcome to OpenSpec!

欢迎使用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.

---
我将带您通过代码库中的实际任务，完整走完一个变更周期——从想法到实现。在此过程中，您将通过实操学习工作流。
我们将完成以下内容：
  1. 在您的代码库中挑选一个小型的实际任务
  2. 简要探究问题
  3. 创建一个变更（我们工作的容器）
  4. 构建工件：提案 → 规格说明 → 设计 → 任务
  5. 实现任务
  6. 归档已完成的变更
预计耗时： ~15-20分钟
让我们从寻找要处理的内容开始。

---

Phase 2: Task Selection

第二阶段：任务选择

Codebase Analysis

代码库分析

Scan the codebase for small improvement opportunities. Look for:
  1. TODO/FIXME comments - Search for 
    TODO
    , 
    FIXME
    , 
    HACK
    , 
    XXX
    in code files
  2. Missing error handling - 
    catch
    blocks that swallow errors, risky operations without try-catch
  3. Functions without tests - Cross-reference 
    src/
    with test directories
  4. Type issues - 
    any
    types in TypeScript files (
    : any
    , 
    as any
    )
  5. Debug artifacts - 
    console.log
    , 
    console.debug
    , 
    debugger
    statements in non-debug code
  6. Missing validation - User input handlers without validation
Also check recent git activity:
bash
git log --oneline -10 2>/dev/null || echo "No git history"
扫描代码库，寻找小型优化机会。重点关注：
  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
git log --oneline -10 2>/dev/null || echo "No git history"

Present Suggestions

呈现建议

From your analysis, present 3-4 specific suggestions:
undefined
根据分析结果，呈现3-4个具体建议：
undefined

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)

**If nothing found:** Fall back to asking what the user wants to build:
> I didn't find obvious quick wins in your codebase. What's something small you've been meaning to add or fix?
基于对您代码库的扫描，以下是一些适合入门的任务：
1. [最具价值的任务] 位置：
src/path/to/file.ts:42
范围：约1-2个文件，20-30行代码 推荐理由：[简短说明]
2. [第二个任务] 位置：
src/another/file.ts
范围：约1个文件，15行代码 推荐理由：[简短说明]
3. [第三个任务] 位置：[具体位置] 范围：[预估规模] 推荐理由：[简短说明]
4. 其他任务？ 告诉我您想处理什么内容。
您对哪个任务感兴趣？（选择编号或描述您自己的任务）

**如果未找到合适任务：** 退而询问用户想要构建什么：
> 我在您的代码库中未找到明显的快速优化点。您有没有一直想添加或修复的小功能？

Scope Guardrail

范围管控

If the user picks or describes something too large (major feature, multi-day work):
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?
Let the user override if they insist—this is a soft guardrail.
如果用户选择或描述的任务过大（如大型功能、需要多天完成的工作）：
这是一个很有价值的任务，但对于您第一次使用OpenSpec的入门体验来说，它的规模可能偏大。

为了学习工作流，任务越小越好——这样您可以在不陷入实现细节的情况下，完整体验整个周期。

**选项：**
1. **拆分任务** - [用户所选任务]中最小的可用模块是什么？比如仅实现[具体子任务]？
2. **更换任务** - 选择其他建议中的一个，或者另一个小型任务？
3. **继续原任务** - 如果您确实想处理这个任务，我们也可以进行。只是需要注意这会花费更长时间。

您更倾向于哪种选择？
如果用户坚持，可以允许他们选择原任务——这只是一个软性管控。

Phase 3: Explore Demo

第三阶段：探索演示

Once a task is selected, briefly demonstrate explore mode:
Before we create a change, let me quickly show you **explore mode**—it's how you think through problems before committing to a direction.
Spend 1-2 minutes investigating the relevant code:
  • Read the file(s) involved
  • Draw a quick ASCII diagram if it helps
  • Note any considerations
undefined
选定任务后，简要演示探索模式：
在创建变更之前，让我快速向您展示**探索模式**——这是我们在确定方向之前，梳理问题的方式。
花1-2分钟研究相关代码：
  • 阅读涉及的文件
  • 如果有帮助，可以绘制简单的ASCII图
  • 记录需要注意的事项
undefined

Quick Exploration

快速探索

[Your brief analysis—what you found, any considerations]
┌─────────────────────────────────────────┐ │ [Optional: ASCII diagram if helpful] │ └─────────────────────────────────────────┘
Explore mode (
/opsx: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.

**PAUSE** - Wait for user acknowledgment before proceeding.

---
[您的简要分析——发现的内容、需要注意的事项]
┌─────────────────────────────────────────┐ │ [可选：如有帮助可添加ASCII图] │ └─────────────────────────────────────────┘
探索模式（
/opsx:explore
）就是用于这类场景——在实现前进行调研。您可以在任何需要梳理问题的时候使用它。
现在让我们创建一个变更来承载我们的工作。

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

---

Phase 4: Create the Change

第四阶段：创建变更

EXPLAIN:
undefined
讲解：
undefined

Creating a Change

创建变更

A "change" in OpenSpec is a container for all the thinking and planning around a piece of work. It lives in 
openspec/changes/<name>/
and holds your artifacts—proposal, specs, design, tasks.
Let me create one for our task.

**DO:** Create the change with a derived kebab-case name:

```bash
openspec new change "<derived-name>"
SHOW:
Created: `openspec/changes/<name>/`

The folder structure:
openspec/changes/<name>/ ├── proposal.md ← Why we're doing this (empty, we'll fill it) ├── design.md ← How we'll build it (empty) ├── specs/ ← Detailed requirements (empty) └── tasks.md ← Implementation checklist (empty)

Now let's fill in the first artifact—the proposal.
在OpenSpec中，“变更”是一个容器，用于存放围绕某一项工作的所有思考和规划。它位于
openspec/changes/<name>/
目录下，包含您的所有工件——提案、规格说明、设计、任务。
让我为我们的任务创建一个变更。

**操作：** 使用派生的短横线命名法创建变更：

```bash
openspec new change "<derived-name>"
展示：
已创建：`openspec/changes/<name>/`

目录结构：
openspec/changes/<name>/ ├── proposal.md ← 我们做此项工作的原因（为空，稍后我们会填充） ├── design.md ← 我们将如何实现（为空） ├── specs/ ← 详细需求（为空） └── tasks.md ← 实现清单（为空）

现在让我们填充第一个工件——提案。

Phase 5: Proposal

第五阶段：提案

EXPLAIN:
undefined
讲解：
undefined

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.

**DO:** Draft the proposal content (don't save yet):
Here's a draft proposal:
提案用于记录我们进行此项变更的原因，以及从宏观层面说明变更内容。它是这项工作的“电梯演讲”。
我将根据我们的任务草拟一份提案。

**操作：** 草拟提案内容（暂不保存）：
以下是草拟的提案：

Why

原因

[1-2 sentences explaining the problem/opportunity]
[1-2句话解释问题/优化机会]

What Changes

变更内容

[Bullet points of what will be different]
[列出变更后会产生的不同点]

Capabilities

功能

New Capabilities

新增功能

  • <capability-name>
    : [brief description]
  • <capability-name>
    : [简短描述]

Modified Capabilities

修改功能

<!-- If modifying existing behavior -->
<!-- 如果修改现有行为，请填写 -->

Impact

影响

  • src/path/to/file.ts
    : [what changes]
  • [other files if applicable]
Does this capture the intent? I can adjust before we save it.

**PAUSE** - Wait for user approval/feedback.

After approval, save the proposal:

```bash
openspec instructions proposal --change "<name>" --json
Then write the content to 
openspec/changes/<name>/proposal.md
.
Proposal saved. This is your "why" document—you can always come back and refine it as understanding evolves.

Next up: specs.
  • src/path/to/file.ts
    : [具体变更内容]
  • [其他相关文件（如有）]
这份提案是否准确传达了意图？在保存之前我可以进行调整。

**暂停** - 等待用户确认/反馈。

获得确认后，保存提案：

```bash
openspec instructions proposal --change "<name>" --json
然后将内容写入
openspec/changes/<name>/proposal.md
。
提案已保存。这是您的“原因”文档——随着理解的深入，您可以随时回来完善它。

下一步：规格说明。

Phase 6: Specs

第六阶段：规格说明

EXPLAIN:
undefined
讲解：
undefined

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.

**DO:** Create the spec file:

```bash
mkdir -p openspec/changes/<name>/specs/<capability-name>
Draft the spec content:
Here's the spec:

---
规格说明以精确、可测试的术语定义我们要构建的内容。它们采用“需求/场景”格式，使预期行为清晰明确。
对于像这样的小型任务，我们可能只需要一个规格说明文件。

**操作：** 创建规格说明文件：

```bash
mkdir -p openspec/changes/<name>/specs/<capability-name>
草拟规格说明内容：
以下是规格说明：

---

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.

Save to `openspec/changes/<name>/specs/<capability>/spec.md`.

---
  • 当 <触发条件>
  • 则 <预期结果>
  • 并且 <如有需要可添加额外结果>
这种“当/则/并且”的格式使需求可测试。您可以直接将它们作为测试用例。

将内容保存到`openspec/changes/<name>/specs/<capability>/spec.md`。

---

Phase 7: Design

第七阶段：设计

EXPLAIN:
undefined
讲解：
undefined

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.

**DO:** Draft design.md:
Here's the design:
设计记录我们将如何实现——技术决策、权衡、实现方案。
对于小型变更，设计可以很简洁。这没问题——并非所有变更都需要深入的设计讨论。

**操作：** 草拟design.md：
以下是设计方案：

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]

决策1：[关键决策]

[Explanation of approach and rationale]
For a small task, this captures the key decisions without over-engineering.

Save to `openspec/changes/<name>/design.md`.

---
[对方案和理由的解释]
对于小型任务，这样的设计足以记录关键决策，不会过度设计。

将内容保存到`openspec/changes/<name>/design.md`。

---

Phase 8: Tasks

第八阶段：任务

EXPLAIN:
undefined
讲解：
undefined

Tasks

任务

Finally, we break the work into implementation tasks—checkboxes that drive the apply phase.
These should be small, clear, and in logical order.

**DO:** Generate tasks based on specs and design:
Here are the implementation tasks:
最后，我们将工作拆分为实现任务——这些复选框将驱动实施阶段。
任务应该小而清晰，并且按逻辑顺序排列。

**操作：** 根据规格说明和设计生成任务：
以下是实现任务：

1. [Category or file]

1. [类别或文件]

  • 1.1 [Specific task]
  • 1.2 [Specific task]
  • 1.1 [具体任务]
  • 1.2 [具体任务]

2. Verify

2. 验证

  • 2.1 [Verification step]
Each checkbox becomes a unit of work in the apply phase. Ready to implement?

**PAUSE** - Wait for user to confirm they're ready to implement.

Save to `openspec/changes/<name>/tasks.md`.

---
  • 2.1 [验证步骤]
每个复选框都是实施阶段的一个工作单元。准备好开始实现了吗？

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

将内容保存到`openspec/changes/<name>/tasks.md`。

---

Phase 9: Apply (Implementation)

第九阶段：实施

EXPLAIN:
undefined
讲解：
undefined

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.

**DO:** For each task:

1. Announce: "Working on task N: [description]"
2. Implement the change in the codebase
3. Reference specs/design naturally: "The spec says X, so I'm doing Y"
4. Mark complete in tasks.md: `- [ ]` → `- [x]`
5. Brief status: "✓ Task N complete"

Keep narration light—don't over-explain every line of code.

After all tasks:
现在我们将逐个完成任务，完成后勾选对应的复选框。我会宣布每个任务，并偶尔说明规格说明/设计如何指导实现方案。

**操作：** 对于每个任务：

1. 宣布：“正在处理任务N：[描述]”
2. 在代码库中实现变更
3. 自然引用规格说明/设计：“规格说明要求X，所以我实现Y”
4. 在tasks.md中标记为完成：`- [ ]` → `- [x]`
5. 简要状态更新：“✓ 任务N已完成”

讲解要简洁——无需逐行解释代码。

完成所有任务后：

Implementation Complete

实施完成

All tasks done:
  • Task 1
  • Task 2
  • ...
The change is implemented! One more step—let's archive it.

---
所有任务已完成：
  • 任务1
  • 任务2
  • ...
变更已实现！最后一步——让我们归档它。

---

Phase 10: Archive

第十阶段：归档

EXPLAIN:
undefined
讲解：
undefined

Archiving

归档

When a change is complete, we archive it. This moves it from 
openspec/changes/
to 
openspec/archive/YYYY-MM-DD--<name>/
.
Archived changes become your project's decision history—you can always find them later to understand why something was built a certain way.

**DO:**

```bash
openspec archive "<name>"
SHOW:
Archived to: `openspec/archive/YYYY-MM-DD--<name>/`

The change is now part of your project's history. The code is in your codebase, the decision record is preserved.
当变更完成后，我们将其归档。这会将它从
openspec/changes/
目录移动到
openspec/archive/YYYY-MM-DD--<name>/
目录。
已归档的变更将成为您项目的决策历史——您以后可以随时查看它们，了解某项功能为何采用特定的实现方式。

**操作：**

```bash
openspec archive "<name>"
展示：
已归档至：`openspec/archive/YYYY-MM-DD--<name>/`

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

Phase 11: Recap & Next Steps

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

undefined
undefined

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.
您刚刚完成了一个完整的OpenSpec周期：
  1. 探索 - 梳理问题
  2. 新建 - 创建变更容器
  3. 提案 - 记录原因
  4. 规格说明 - 详细定义内容
  5. 设计 - 确定实现方式
  6. 任务 - 拆分为步骤
  7. 实施 - 完成工作
  8. 归档 - 保存记录
同样的流程适用于任何规模的变更——从小型修复到大型功能。

Command Reference

命令参考

CommandWhat it does
/opsx:explore
Think through problems before/during work
/opsx:new
Start a new change, step through artifacts
/opsx:ff
Fast-forward: create all artifacts at once
/opsx:continue
Continue working on an existing change
/opsx:apply
Implement tasks from a change
/opsx:verify
Verify implementation matches artifacts
/opsx:archive
Archive a completed change
命令功能
/opsx:explore
在工作前/工作中梳理问题
/opsx:new
创建新变更，逐步生成工件
/opsx:ff
快速生成：一次性创建所有工件
/opsx:continue
继续处理现有变更
/opsx:apply
实施变更中的任务
/opsx:verify
验证实施内容是否符合工件要求
/opsx:archive
归档已完成的变更

What's Next?

下一步

Try 
/opsx:new
or 
/opsx:ff
on something you actually want to build. You've got the rhythm now!

---
尝试使用
/opsx:new
或
/opsx:ff
处理您实际想要构建的内容。您已经掌握了流程！

---

Graceful Exit Handling

优雅退出处理

User wants to stop mid-way

用户希望中途停止

If the user says they need to stop, want to pause, or seem disengaged:
No problem! Your change is saved at `openspec/changes/<name>/`.

To pick up where we left off later:
- `/opsx:continue <name>` - Resume artifact creation
- `/opsx:apply <name>` - Jump to implementation (if tasks exist)

The work won't be lost. Come back whenever you're ready.
Exit gracefully without pressure.
如果用户表示需要停止、暂停，或表现出无兴趣：
没问题！您的变更已保存至`openspec/changes/<name>/`。

以后如需继续：
- `/opsx:continue <name>` - 继续创建工件
- `/opsx:apply <name>` - 直接跳至实施阶段（如果已有任务）

工作不会丢失。您可以随时回来继续。
优雅退出，不要给用户压力。

User just wants command reference

用户仅需要命令参考

If the user says they just want to see the commands or skip the tutorial:
undefined
如果用户表示只想查看命令或跳过教程：
undefined

OpenSpec Quick Reference

OpenSpec快速参考

CommandWhat it does
/opsx:explore
Think through problems (no code changes)
/opsx:new <name>
Start a new change, step by step
/opsx:ff <name>
Fast-forward: all artifacts at once
/opsx:continue <name>
Continue an existing change
/opsx:apply <name>
Implement tasks
/opsx:verify <name>
Verify implementation
/opsx:archive <name>
Archive when done
Try 
/opsx:new
to start your first change, or 
/opsx:ff
if you want to move fast.

Exit gracefully.

---
命令功能
/opsx:explore
梳理问题（不修改代码）
/opsx:new <name>
逐步创建新变更
/opsx:ff <name>
快速生成：一次性创建所有工件
/opsx:continue <name>
继续处理现有变更
/opsx:apply <name>
实施任务
/opsx:verify <name>
验证实施内容
/opsx:archive <name>
完成后归档
尝试使用
/opsx:new
开始您的第一个变更，或使用
/opsx:ff
快速推进。

优雅退出。

---

Guardrails

管控规则

  • Follow the EXPLAIN → DO → SHOW → PAUSE pattern at key transitions (after explore, after proposal draft, after tasks, after archive)
  • Keep narration light during implementation—teach without lecturing
  • Don't skip phases even if the change is small—the goal is teaching the workflow
  • Pause for acknowledgment at marked points, but don't over-pause
  • Handle exits gracefully—never pressure the user to continue
  • Use real codebase tasks—don't simulate or use fake examples
  • Adjust scope gently—guide toward smaller tasks but respect user choice
  • 在关键过渡点（探索后、提案草拟后、任务生成后、归档后）遵循讲解 → 操作 → 展示 → 暂停的模式
  • 实施阶段的讲解要简洁——教学但不说教
  • 即使变更很小，也不要跳过任何阶段——目标是教授工作流
  • 在标记的点暂停等待确认，但不要过度暂停
  • 优雅处理退出——永远不要给用户施加继续的压力
  • 使用真实的代码库任务——不要模拟或使用虚假示例
  • 温和调整范围——引导用户选择小型任务，但尊重用户选择