fix

.opencode/skills/openspec-onboard/SKILL.cn.md

@@ -0,0 +1,529 @@
+---
+name: openspec-onboard
+description: OpenSpec 引导式入门教程 - 通过真实代码库工作完整演示工作流程
+license: MIT
+compatibility: 需要 openspec CLI。
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.1.1"
+---
+
+引导用户完成他们的第一个完整 OpenSpec 工作流程周期。这是一次教学体验——你将在他们的代码库中做真实的工作,同时解释每个步骤。
+
+---
+
+## 准备检查
+
+在开始之前,检查 OpenSpec 是否已初始化:
+
+```bash
+openspec status --json 2>&1 || echo "NOT_INITIALIZED"
+```
+
+**如果未初始化:**
+> OpenSpec 还未在此项目中设置。请先运行 `openspec init`,然后再回到 `/opsx-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
+git log --oneline -10 2>/dev/null || 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 图]        │
+└─────────────────────────────────────────┘
+
+探索模式 (`/opsx-explore`) 就是用于这种思考——在实现之前进行调查。你可以在需要思考问题时随时使用它。
+
+现在让我们创建一个变更来保存我们的工作。
+```
+
+**暂停** - 等待用户确认后再继续。
+
+---
+
+## 阶段 4: 创建变更
+
+**解释:**
+```
+## 创建变更
+
+在 OpenSpec 中,"变更"是围绕一项工作的所有思考和规划的容器。它位于 `openspec/changes/<name>/` 中,包含你的工件——proposal、specs、design、tasks。
+
+让我为我们的任务创建一个。
+```
+
+**执行:** 使用派生的 kebab-case 名称创建变更:
+```bash
+openspec new change "<derived-name>"
+```
+
+**显示:**
+```
+创建: `openspec/changes/<name>/`
+
+文件夹结构:
+```
+openspec/changes/<name>/
+├── proposal.md    ← 我们为什么这样做(空的,我们会填充)
+├── design.md      ← 我们如何构建它(空的)
+├── specs/         ← 详细需求(空的)
+└── tasks.md       ← 实现检查清单(空的)
+```
+
+现在让我们填充第一个工件——proposal。
+```
+
+---
+
+## 阶段 5: Proposal
+
+**解释:**
+```
+## Proposal
+
+proposal 捕获我们为什么进行这个变更以及高层次的内容。这是工作的"电梯演讲"。
+
+我将根据我们的任务起草一个。
+```
+
+**执行:** 起草 proposal 内容(还不要保存):
+
+```
+这是一个草案 proposal:
+
+---
+
+## 为什么 (Why)
+
+[1-2 句话解释问题/机会]
+
+## 变更内容 (What Changes)
+
+[将会有什么不同的要点]
+
+## 能力 (Capabilities)
+
+### 新能力
+- `<capability-name>`: [简要描述]
+
+### 修改的能力
+<!-- 如果修改现有行为 -->
+
+## 影响 (Impact)
+
+- `src/path/to/file.ts`: [什么变更]
+- [其他适用的文件]
+
+---
+
+这是否捕获了意图? 我可以在保存前调整。
+```
+
+**暂停** - 等待用户批准/反馈。
+
+批准后,保存 proposal:
+```bash
+openspec instructions proposal --change "<name>" --json
+```
+然后将内容写入 `openspec/changes/<name>/proposal.md`。
+
+```
+Proposal 已保存。这是你的"为什么"文档——随着理解的演变,你总是可以回来完善它。
+
+接下来: specs。
+```
+
+---
+
+## 阶段 6: Specs
+
+**解释:**
+```
+## Specs
+
+Specs 以精确、可测试的术语定义我们正在构建什么。它们使用需求/场景格式,使预期行为非常清晰。
+
+对于像这样的小任务,我们可能只需要一个 spec 文件。
+```
+
+**执行:** 创建 spec 文件:
+```bash
+mkdir -p 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`。
+
+---
+
+## 阶段 7: Design
+
+**解释:**
+```
+## Design
+
+design 捕获我们如何构建它——技术决策、权衡、方法。
+
+对于小变更,这可能很简短。这没关系——不是每个变更都需要深度设计讨论。
+```
+
+**执行:** 起草 design.md:
+
+```
+这是 design:
+
+---
+
+## 上下文 (Context)
+
+[关于当前状态的简要上下文]
+
+## 目标 / 非目标 (Goals / Non-Goals)
+
+**目标:**
+- [我们试图实现什么]
+
+**非目标:**
+- [明确超出范围的内容]
+
+## 决策 (Decisions)
+
+### Decision 1: [关键决策]
+
+[方法和理由的解释]
+
+---
+
+对于小任务,这捕获了关键决策而不会过度设计。
+```
+
+保存到 `openspec/changes/<name>/design.md`。
+
+---
+
+## 阶段 8: Tasks
+
+**解释:**
+```
+## Tasks
+
+最后,我们将工作分解为实现任务——驱动应用阶段的复选框。
+
+这些应该小、清晰且按逻辑顺序排列。
+```
+
+**执行:** 基于 specs 和 design 生成任务:
+
+```
+这是实现任务:
+
+---
+
+## 1. [类别或文件]
+
+- [ ] 1.1 [具体任务]
+- [ ] 1.2 [具体任务]
+
+## 2. 验证 (Verify)
+
+- [ ] 2.1 [验证步骤]
+
+---
+
+每个复选框在应用阶段成为一个工作单元。准备好实现了吗?
+```
+
+**暂停** - 等待用户确认他们准备好实现。
+
+保存到 `openspec/changes/<name>/tasks.md`。
+
+---
+
+## 阶段 9: Apply (实现)
+
+**解释:**
+```
+## 实现 (Implementation)
+
+现在我们实现每个任务,在进行时勾选它们。我会宣布每一个,偶尔注意 specs/design 如何指导方法。
+```
+
+**执行:** 对于每个任务:
+
+1. 宣布: "正在处理任务 N: [描述]"
+2. 在代码库中进行所需的更改
+3. 自然地引用 specs/design: "spec 说 X,所以我做 Y"
+4. 在 tasks.md 中标记完成: `- [ ]` → `- [x]`
+5. 简要状态: "✓ 任务 N 完成"
+
+保持叙述轻量——不要过度解释每行代码。
+
+所有任务完成后:
+
+```
+## 实现完成
+
+所有任务完成:
+- [x] Task 1
+- [x] Task 2
+- [x] ...
+
+变更已实现! 还有一步——让我们归档它。
+```
+
+---
+
+## 阶段 10: Archive
+
+**解释:**
+```
+## 归档 (Archiving)
+
+当变更完成时,我们归档它。这将它从 `openspec/changes/` 移动到 `openspec/changes/archive/YYYY-MM-DD-<name>/`。
+
+归档的变更成为你项目的决策历史——你总是可以在以后找到它们,以了解为什么某些东西是以某种方式构建的。
+```
+
+**执行:**
+```bash
+openspec archive "<name>"
+```
+
+**显示:**
+```
+归档到: `openspec/changes/archive/YYYY-MM-DD-<name>/`
+
+变更现在是你项目历史的一部分。代码在你的代码库中,决策记录被保存。
+```
+
+---
+
+## 阶段 11: 回顾与下一步
+
+```
+## 恭喜!
+
+你刚刚完成了一个完整的 OpenSpec 周期:
+
+1. **Explore** - 思考问题
+2. **New** - 创建变更容器
+3. **Proposal** - 捕获为什么 (WHY)
+4. **Specs** - 详细定义什么 (WHAT)
+5. **Design** - 决定如何 (HOW)
+6. **Tasks** - 分解为步骤
+7. **Apply** - 实现工作
+8. **Archive** - 保存记录
+
+这个相同的节奏适用于任何规模的变更——无论是小修复还是主要功能。
+
+---
+
+## 命令参考
+
+| 命令 | 功能 |
+|---------|--------------|
+| `/opsx-explore` | 在工作前/期间思考问题 |
+| `/opsx-new` | 启动新变更,逐步完成工件 |
+| `/opsx-ff` | 快进: 一次创建所有工件 |
+| `/opsx-continue` | 继续现有变更的工作 |
+| `/opsx-apply` | 实现变更中的任务 |
+| `/opsx-verify` | 验证实现与工件匹配 |
+| `/opsx-archive` | 归档完成的变更 |
+
+---
+
+## 下一步是什么?
+
+在你真正想构建的东西上尝试 `/opsx-new` 或 `/opsx-ff`。你现在已经掌握了节奏!
+```
+
+---
+
+## 优雅退出处理
+
+### 用户想中途停止
+
+如果用户说他们需要停止、想暂停或看起来不再参与:
+
+```
+没问题! 你的变更保存在 `openspec/changes/<name>/`。
+
+要在以后从我们离开的地方继续:
+- `/opsx-continue <name>` - 恢复工件创建
+- `/opsx-apply <name>` - 跳转到实现(如果任务存在)
+
+工作不会丢失。准备好时随时回来。
+```
+
+优雅退出,不施加压力。
+
+### 用户只想要命令参考
+
+如果用户说他们只想看命令或跳过教程:
+
+```
+## OpenSpec 快速参考
+
+| 命令 | 功能 |
+|---------|--------------|
+| `/opsx-explore` | 思考问题(不改代码) |
+| `/opsx-new <name>` | 启动新变更,逐步进行 |
+| `/opsx-ff <name>` | 快进: 一次所有工件 |
+| `/opsx-continue <name>` | 继续现有变更 |
+| `/opsx-apply <name>` | 实现任务 |
+| `/opsx-verify <name>` | 验证实现 |
+| `/opsx-archive <name>` | 完成时归档 |
+
+试试 `/opsx-new` 来开始你的第一个变更,或者如果你想快速移动就用 `/opsx-ff`。
+```
+
+优雅退出。
+
+---
+
+## 守护
+
+- **遵循 EXPLAIN → DO → SHOW → PAUSE 模式** 在关键转换点(探索后、proposal 草案后、任务后、归档后)
+- **保持叙述轻量** 在实现期间——教学但不说教
+- **不要跳过阶段** 即使变更很小——目标是教学工作流程
+- **在标记的点暂停等待确认**,但不要过度暂停
+- **优雅处理退出**——永远不要强迫用户继续
+- **使用真实代码库任务**——不要模拟或使用假例子
+- **温和地调整范围**——引导向更小的任务但尊重用户选择

.opencode/skills/openspec-onboard/SKILL.md

@@ -0,0 +1,529 @@
+---
+name: openspec-onboard
+description: Guided onboarding for OpenSpec - walk through a complete workflow cycle with narration and real codebase work.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.1.1"
+---
+
+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.
+
+---
+
+## 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.
+
+---
+
+## Phase 1: Welcome
+
+Display:
+
+```
+## 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.
+```
+
+---
+
+## 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"
+```
+
+### Present Suggestions
+
+From your analysis, present 3-4 specific suggestions:
+
+```
+## 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?
+
+### 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.
+
+---
+
+## 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
+
+```
+## 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.
+
+---
+
+## Phase 4: Create the Change
+
+**EXPLAIN:**
+```
+## 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.
+```
+
+---
+
+## Phase 5: Proposal
+
+**EXPLAIN:**
+```
+## 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]
+
+## What Changes
+
+[Bullet points of what will be different]
+
+## Capabilities
+
+### New Capabilities
+- `<capability-name>`: [brief description]
+
+### 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.
+```
+
+---
+
+## Phase 6: Specs
+
+**EXPLAIN:**
+```
+## 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:
+
+---
+
+## 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`.
+
+---
+
+## Phase 7: Design
+
+**EXPLAIN:**
+```
+## 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:
+
+---
+
+## 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.
+```
+
+Save to `openspec/changes/<name>/design.md`.
+
+---
+
+## Phase 8: Tasks
+
+**EXPLAIN:**
+```
+## 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 [Specific task]
+- [ ] 1.2 [Specific task]
+
+## 2. Verify
+
+- [ ] 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`.
+
+---
+
+## Phase 9: Apply (Implementation)
+
+**EXPLAIN:**
+```
+## 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:
+
+```
+## Implementation Complete
+
+All tasks done:
+- [x] Task 1
+- [x] Task 2
+- [x] ...
+
+The change is implemented! One more step—let's archive it.
+```
+
+---
+
+## Phase 10: Archive
+
+**EXPLAIN:**
+```
+## Archiving
+
+When a change is complete, we archive it. This moves it from `openspec/changes/` to `openspec/changes/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/changes/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.
+```
+
+---
+
+## Phase 11: Recap & Next Steps
+
+```
+## 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
+
+| Command | What 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 |
+
+---
+
+## What's Next?
+
+Try `/opsx-new` or `/opsx-ff` on something you actually want to build. You've got the rhythm now!
+```
+
+---
+
+## 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.
+
+### User just wants command reference
+
+If the user says they just want to see the commands or skip the tutorial:
+
+```
+## OpenSpec Quick Reference
+
+| Command | What 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.
+
+---
+
+## 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