diff --git a/AGENTS.md b/AGENTS.md
index 7f111dd7..dc71cc99 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,18 +1,18 @@
-# OpenSpec Instructions
+# OpenSpec 指令
-These instructions are for AI assistants working in this project.
+这些指令适用于在此项目中工作的 AI 助手。
-Always open `@/openspec/AGENTS.md` when the request:
-- Mentions planning or proposals (words like proposal, spec, change, plan)
-- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
-- Sounds ambiguous and you need the authoritative spec before coding
+当请求满足以下条件时，始终打开 `@/openspec/AGENTS.md`：
+- 提到规划或提案（如 proposal、spec、change、plan 等词）
+- 引入新功能、破坏性变更、架构转变或重大性能/安全工作
+- 听起来模糊，您需要在编码前查看权威规范
-Use `@/openspec/AGENTS.md` to learn:
-- How to create and apply change proposals
-- Spec format and conventions
-- Project structure and guidelines
+使用 `@/openspec/AGENTS.md` 学习：
+- 如何创建和应用变更提案
+- 规范格式和约定
+- 项目结构和指南
-Keep this managed block so 'openspec update' can refresh the instructions.
+保留此托管块，以便 'openspec update' 可以刷新指令。
diff --git a/AGENTS.zh-CN.md b/AGENTS.zh-CN.md
new file mode 100644
index 00000000..dc71cc99
--- /dev/null
+++ b/AGENTS.zh-CN.md
@@ -0,0 +1,18 @@
+
+# OpenSpec 指令
+
+这些指令适用于在此项目中工作的 AI 助手。
+
+当请求满足以下条件时，始终打开 `@/openspec/AGENTS.md`：
+- 提到规划或提案（如 proposal、spec、change、plan 等词）
+- 引入新功能、破坏性变更、架构转变或重大性能/安全工作
+- 听起来模糊，您需要在编码前查看权威规范
+
+使用 `@/openspec/AGENTS.md` 学习：
+- 如何创建和应用变更提案
+- 规范格式和约定
+- 项目结构和指南
+
+保留此托管块，以便 'openspec update' 可以刷新指令。
+
+
diff --git a/README.md b/README.md
index 7b6c7354..29273336 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
-Spec-driven development for AI coding assistants.
+为 AI 编码助手提供规范驱动的开发方式。
@@ -23,83 +23,85 @@
- Follow @0xTab on X for updates · Join the OpenSpec Discord for help and questions.
+ 在 X 上关注 @0xTab 获取更新 · 加入 OpenSpec Discord 寻求帮助和提问。
+> [English Version](README.md)
+
# OpenSpec
-OpenSpec aligns humans and AI coding assistants with spec-driven development so you agree on what to build before any code is written. **No API keys required.**
+OpenSpec 通过规范驱动的开发方式，让人类和 AI 编码助手在编写任何代码之前就对要构建的内容达成一致。**无需 API 密钥。**
-## Why OpenSpec?
+## 为什么选择 OpenSpec？
-AI coding assistants are powerful but unpredictable when requirements live in chat history. OpenSpec adds a lightweight specification workflow that locks intent before implementation, giving you deterministic, reviewable outputs.
+AI 编码助手功能强大，但当需求存在于聊天历史中时，它们的行为是不可预测的。OpenSpec 添加了一个轻量级的规范工作流，在实施之前锁定意图，为您提供确定性的、可审查的输出。
-Key outcomes:
-- Human and AI stakeholders agree on specs before work begins.
-- Structured change folders (proposals, tasks, and spec updates) keep scope explicit and auditable.
-- Shared visibility into what's proposed, active, or archived.
-- Works with the AI tools you already use: custom slash commands where supported, context rules everywhere else.
+主要成果：
+- 人类和 AI 利益相关者在工作开始前就规范达成一致。
+- 结构化的变更文件夹（提案、任务和规范更新）使范围明确且可审计。
+- 对提议的、活跃的或已归档的内容具有共享可见性。
+- 与您已经使用的 AI 工具配合使用：在支持的地方使用自定义斜杠命令，在其他地方使用上下文规则。
-## How OpenSpec compares (at a glance)
+## OpenSpec 的比较（概览）
-- **Lightweight**: simple workflow, no API keys, minimal setup.
-- **Brownfield-first**: works great beyond 0→1. OpenSpec separates the source of truth from proposals: `openspec/specs/` (current truth) and `openspec/changes/` (proposed updates). This keeps diffs explicit and manageable across features.
-- **Change tracking**: proposals, tasks, and spec deltas live together; archiving merges the approved updates back into specs.
-- **Compared to spec-kit & Kiro**: those shine for brand-new features (0→1). OpenSpec also excels when modifying existing behavior (1→n), especially when updates span multiple specs.
+- **轻量级**：简单的工作流程，无需 API 密钥，最小化设置。
+- **优先支持现有项目**：不仅适用于从零开始的项目。OpenSpec 将真实来源与提案分离：`openspec/specs/`（当前真实状态）和 `openspec/changes/`（提议的更新）。这使得跨功能的差异保持明确和可管理。
+- **变更跟踪**：提案、任务和规范增量放在一起；归档将批准的更新合并回规范。
+- **与 spec-kit 和 Kiro 的比较**：这些工具在全新功能（0→1）方面表现出色。OpenSpec 在修改现有行为（1→n）时也很出色，特别是当更新跨越多个规范时。
-See the full comparison in [How OpenSpec Compares](#how-openspec-compares).
+查看 [OpenSpec 的比较](#openspec-的比较详细说明) 了解完整对比。
-## How It Works
+## 工作原理
```
┌────────────────────┐
-│ Draft Change │
-│ Proposal │
+│ 起草变更提案 │
+│ │
└────────┬───────────┘
- │ share intent with your AI
+ │ 与您的 AI 分享意图
▼
┌────────────────────┐
-│ Review & Align │
-│ (edit specs/tasks) │◀──── feedback loop ──────┐
-└────────┬───────────┘ │
- │ approved plan │
- ▼ │
-┌────────────────────┐ │
-│ Implement Tasks │──────────────────────────┘
-│ (AI writes code) │
+│ 审查与对齐 │
+│ (编辑规范/任务) │◀──── 反馈循环 ──────┐
+└────────┬───────────┘ │
+ │ 批准的计划 │
+ ▼ │
+┌────────────────────┐ │
+│ 实施任务 │──────────────────────┘
+│ (AI 编写代码) │
└────────┬───────────┘
- │ ship the change
+ │ 发布变更
▼
┌────────────────────┐
-│ Archive & Update │
-│ Specs (source) │
+│ 归档并更新 │
+│ 规范（源） │
└────────────────────┘
-1. Draft a change proposal that captures the spec updates you want.
-2. Review the proposal with your AI assistant until everyone agrees.
-3. Implement tasks that reference the agreed specs.
-4. Archive the change to merge the approved updates back into the source-of-truth specs.
+1. 起草一个变更提案，捕获您想要的规范更新。
+2. 与您的 AI 助手一起审查提案，直到每个人都同意。
+3. 实施引用已同意规范的任务。
+4. 归档变更，将批准的更新合并回真实来源规范。
```
-## Getting Started
+## 入门指南
-### Supported AI Tools
+### 支持的 AI 工具
-Native Slash Commands (click to expand)
+原生斜杠命令（点击展开）
-These tools have built-in OpenSpec commands. Select the OpenSpec integration when prompted.
+这些工具具有内置的 OpenSpec 命令。在提示时选择 OpenSpec 集成。
-| Tool | Commands |
+| 工具 | 命令 |
|------|----------|
| **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` (`.amazonq/prompts/`) |
| **Antigravity** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.agent/workflows/`) |
| **Auggie (Augment CLI)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.augment/commands/`) |
| **Claude Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` |
-| **Cline** | Workflows in `.clinerules/workflows/` directory (`.clinerules/workflows/openspec-*.md`) |
-| **CodeBuddy Code (CLI)** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.codebuddy/commands/`) — see [docs](https://www.codebuddy.ai/cli) |
-| **Codex** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (global: `~/.codex/prompts`, auto-installed) |
-| **CoStrict** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.cospec/openspec/commands/`) — see [docs](https://costrict.ai)|
+| **Cline** | `.clinerules/workflows/` 目录中的工作流 (`.clinerules/workflows/openspec-*.md`) |
+| **CodeBuddy Code (CLI)** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.codebuddy/commands/`) — 查看 [文档](https://www.codebuddy.ai/cli) |
+| **Codex** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (全局: `~/.codex/prompts`, 自动安装) |
+| **CoStrict** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.cospec/openspec/commands/`) — 查看 [文档](https://costrict.ai)|
| **Crush** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.crush/commands/openspec/`) |
| **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
| **Factory Droid** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.factory/commands/`) |
@@ -108,274 +110,273 @@ These tools have built-in OpenSpec commands. Select the OpenSpec integration whe
| **iFlow (iflow-cli)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.iflow/commands/`) |
| **Kilo Code** | `/openspec-proposal.md`, `/openspec-apply.md`, `/openspec-archive.md` (`.kilocode/workflows/`) |
| **OpenCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
-| **Qoder (CLI)** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.qoder/commands/openspec/`) — see [docs](https://qoder.com/cli) |
+| **Qoder (CLI)** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.qoder/commands/openspec/`) — 查看 [文档](https://qoder.com/cli) |
| **Qwen Code** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.qwen/commands/`) |
| **RooCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.roo/commands/`) |
| **Windsurf** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.windsurf/workflows/`) |
-Kilo Code discovers team workflows automatically. Save the generated files under `.kilocode/workflows/` and trigger them from the command palette with `/openspec-proposal.md`, `/openspec-apply.md`, or `/openspec-archive.md`.
+Kilo Code 自动发现团队工作流。将生成的文件保存在 `.kilocode/workflows/` 下，并使用 `/openspec-proposal.md`、`/openspec-apply.md` 或 `/openspec-archive.md` 从命令面板触发它们。
-AGENTS.md Compatible (click to expand)
+兼容 AGENTS.md（点击展开）
-These tools automatically read workflow instructions from `openspec/AGENTS.md`. Ask them to follow the OpenSpec workflow if they need a reminder. Learn more about the [AGENTS.md convention](https://agents.md/).
+这些工具会自动从 `openspec/AGENTS.md` 读取工作流指令。如果它们需要提醒，请要求它们遵循 OpenSpec 工作流。了解更多关于 [AGENTS.md 约定](https://agents.md/)。
-| Tools |
+| 工具 |
|-------|
-| Amp • Jules • Others |
+| Amp • Jules • 其他 |
-### Install & Initialize
+### 安装与初始化
-#### Prerequisites
-- **Node.js >= 20.19.0** - Check your version with `node --version`
+#### 前提条件
+- **Node.js >= 20.19.0** - 使用 `node --version` 检查您的版本
-#### Step 1: Install the CLI globally
+#### 步骤 1：全局安装 CLI
```bash
npm install -g @fission-ai/openspec@latest
```
-Verify installation:
+验证安装：
```bash
openspec --version
```
-#### Step 2: Initialize OpenSpec in your project
+#### 步骤 2：在您的项目中初始化 OpenSpec
-Navigate to your project directory:
+导航到您的项目目录：
```bash
cd my-project
```
-Run the initialization:
+运行初始化：
```bash
openspec init
```
-**What happens during initialization:**
-- You'll be prompted to pick any natively supported AI tools (Claude Code, CodeBuddy, Cursor, OpenCode, Qoder,etc.); other assistants always rely on the shared `AGENTS.md` stub
-- OpenSpec automatically configures slash commands for the tools you choose and always writes a managed `AGENTS.md` hand-off at the project root
-- A new `openspec/` directory structure is created in your project
+**初始化期间会发生什么：**
+- 系统会提示您选择任何原生支持的 AI 工具（Claude Code、CodeBuddy、Cursor、OpenCode、Qoder 等）；其他助手始终依赖共享的 `AGENTS.md` 存根
+- OpenSpec 会自动为您选择的工具配置斜杠命令，并始终在项目根目录编写一个托管的 `AGENTS.md` 交接文件
+- 在您的项目中创建一个新的 `openspec/` 目录结构
-**After setup:**
-- Primary AI tools can trigger `/openspec` workflows without additional configuration
-- Run `openspec list` to verify the setup and view any active changes
-- If your coding assistant doesn't surface the new slash commands right away, restart it. Slash commands are loaded at startup,
- so a fresh launch ensures they appear
+**设置后：**
+- 主要的 AI 工具可以在不需要额外配置的情况下触发 `/openspec` 工作流
+- 运行 `openspec list` 以验证设置并查看任何活跃的变更
+- 如果您的编码助手没有立即显示新的斜杠命令，请重新启动它。斜杠命令在启动时加载，因此重新启动可确保它们出现
-### Optional: Populate Project Context
+### 可选：填充项目上下文
-After `openspec init` completes, you'll receive a suggested prompt to help populate your project context:
+`openspec init` 完成后，您将收到一个建议的提示，以帮助填充您的项目上下文：
```text
-Populate your project context:
-"Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions"
+填充您的项目上下文：
+"请阅读 openspec/project.md 并帮我填写有关我的项目、技术栈和约定的详细信息"
```
-Use `openspec/project.md` to define project-level conventions, standards, architectural patterns, and other guidelines that should be followed across all changes.
+使用 `openspec/project.md` 定义项目级别的约定、标准、架构模式和其他应在所有变更中遵循的指南。
-### Create Your First Change
+### 创建您的第一个变更
-Here's a real example showing the complete OpenSpec workflow. This works with any AI tool. Those with native slash commands will recognize the shortcuts automatically.
+这是一个展示完整 OpenSpec 工作流的真实示例。这适用于任何 AI 工具。具有原生斜杠命令的工具将自动识别快捷方式。
-#### 1. Draft the Proposal
-Start by asking your AI to create a change proposal:
+#### 1. 起草提案
+首先要求您的 AI 创建一个变更提案：
```text
-You: Create an OpenSpec change proposal for adding profile search filters by role and team
- (Shortcut for tools with slash commands: /openspec:proposal Add profile search filters)
+您：为按角色和团队添加个人资料搜索过滤器创建一个 OpenSpec 变更提案
+ （具有斜杠命令的工具的快捷方式：/openspec:proposal 添加个人资料搜索过滤器）
-AI: I'll create an OpenSpec change proposal for profile filters.
- *Scaffolds openspec/changes/add-profile-filters/ with proposal.md, tasks.md, spec deltas.*
+AI：我将为个人资料过滤器创建一个 OpenSpec 变更提案。
+ *使用 proposal.md、tasks.md、规范增量搭建 openspec/changes/add-profile-filters/。*
```
-#### 2. Verify & Review
-Check that the change was created correctly and review the proposal:
+#### 2. 验证与审查
+检查变更是否正确创建并审查提案：
```bash
-$ openspec list # Confirm the change folder exists
-$ openspec validate add-profile-filters # Validate spec formatting
-$ openspec show add-profile-filters # Review proposal, tasks, and spec delta
+$ openspec list # 确认变更文件夹存在
+$ openspec validate add-profile-filters # 验证规范格式
+$ openspec show add-profile-filters # 审查提案、任务和规范增量
```
-#### 3. Refine the Specs
-Iterate on the specifications until they match your needs:
+#### 3. 完善规范
+迭代规范，直到它们符合您的需求：
```text
-You: Can you add acceptance criteria for the role and team filters?
+您：您能为角色和团队过滤器添加验收标准吗？
-AI: I'll update the spec delta with scenarios for role and team filters.
- *Edits openspec/changes/add-profile-filters/specs/profile/spec.md and tasks.md.*
+AI：我将使用角色和团队过滤器的场景更新规范增量。
+ *编辑 openspec/changes/add-profile-filters/specs/profile/spec.md 和 tasks.md。*
```
-#### 4. Implement the Change
-Once specs look good, start implementation:
+#### 4. 实施变更
+一旦规范看起来不错，开始实施：
```text
-You: The specs look good. Let's implement this change.
- (Shortcut for tools with slash commands: /openspec:apply add-profile-filters)
+您：规范看起来不错。让我们实施这个变更。
+ （具有斜杠命令的工具的快捷方式：/openspec:apply add-profile-filters）
-AI: I'll work through the tasks in the add-profile-filters change.
- *Implements tasks from openspec/changes/add-profile-filters/tasks.md*
- *Marks tasks complete: Task 1.1 ✓, Task 1.2 ✓, Task 2.1 ✓...*
+AI：我将完成 add-profile-filters 变更中的任务。
+ *从 openspec/changes/add-profile-filters/tasks.md 实施任务*
+ *标记任务完成：任务 1.1 ✓，任务 1.2 ✓，任务 2.1 ✓...*
```
-#### 5. Archive the Completed Change
-After implementation is complete, archive the change:
+#### 5. 归档已完成的变更
+实施完成后，归档变更：
```text
-AI: All tasks are complete. The implementation is ready.
+AI：所有任务都已完成。实施已准备就绪。
-You: Please archive the change
- (Shortcut for tools with slash commands: /openspec:archive add-profile-filters)
+您：请归档变更
+ （具有斜杠命令的工具的快捷方式：/openspec:archive add-profile-filters）
-AI: I'll archive the add-profile-filters change.
- *Runs: openspec archive add-profile-filters --yes*
- ✓ Change archived successfully. Specs updated. Ready for the next feature!
+AI：我将归档 add-profile-filters 变更。
+ *运行：openspec archive add-profile-filters --yes*
+ ✓ 变更已成功归档。规范已更新。准备好下一个功能！
```
-Or run the command yourself in terminal:
+或者在终端中自己运行命令：
```bash
-$ openspec archive add-profile-filters --yes # Archive the completed change without prompts
+$ openspec archive add-profile-filters --yes # 无提示归档已完成的变更
```
-**Note:** Tools with native slash commands (Claude Code, CodeBuddy, Cursor, Codex, Qoder, RooCode) can use the shortcuts shown. All other tools work with natural language requests to "create an OpenSpec proposal", "apply the OpenSpec change", or "archive the change".
+**注意：** 具有原生斜杠命令的工具（Claude Code、CodeBuddy、Cursor、Codex、Qoder、RooCode）可以使用显示的快捷方式。所有其他工具都使用自然语言请求"创建 OpenSpec 提案"、"应用 OpenSpec 变更"或"归档变更"。
-## Command Reference
+## 命令参考
```bash
-openspec list # View active change folders
-openspec view # Interactive dashboard of specs and changes
-openspec show # Display change details (proposal, tasks, spec updates)
-openspec validate # Check spec formatting and structure
-openspec archive [--yes|-y] # Move a completed change into archive/ (non-interactive with --yes)
+openspec list # 查看活跃的变更文件夹
+openspec view # 规范和变更的交互式仪表板
+openspec show # 显示变更详细信息（提案、任务、规范更新）
+openspec validate # 检查规范格式和结构
+openspec archive [--yes|-y] # 将已完成的变更移动到 archive/（使用 --yes 进行非交互式操作）
```
-## Example: How AI Creates OpenSpec Files
+## 示例：AI 如何创建 OpenSpec 文件
-When you ask your AI assistant to "add two-factor authentication", it creates:
+当您要求 AI 助手"添加双因素身份验证"时，它会创建：
```
openspec/
├── specs/
│ └── auth/
-│ └── spec.md # Current auth spec (if exists)
+│ └── spec.md # 当前的身份验证规范（如果存在）
└── changes/
- └── add-2fa/ # AI creates this entire structure
- ├── proposal.md # Why and what changes
- ├── tasks.md # Implementation checklist
- ├── design.md # Technical decisions (optional)
+ └── add-2fa/ # AI 创建整个结构
+ ├── proposal.md # 为什么以及什么变更
+ ├── tasks.md # 实施清单
+ ├── design.md # 技术决策（可选）
└── specs/
└── auth/
- └── spec.md # Delta showing additions
+ └── spec.md # 显示添加内容的增量
```
-### AI-Generated Spec (created in `openspec/specs/auth/spec.md`):
+### AI 生成的规范（在 `openspec/specs/auth/spec.md` 中创建）：
```markdown
-# Auth Specification
+# 身份验证规范
-## Purpose
-Authentication and session management.
+## 目的
+身份验证和会话管理。
-## Requirements
-### Requirement: User Authentication
-The system SHALL issue a JWT on successful login.
+## 需求
+### 需求：用户身份验证
+系统应在成功登录时发出 JWT。
-#### Scenario: Valid credentials
-- WHEN a user submits valid credentials
-- THEN a JWT is returned
+#### 场景：有效凭据
+- 当用户提交有效凭据时
+- 则返回 JWT
```
-### AI-Generated Change Delta (created in `openspec/changes/add-2fa/specs/auth/spec.md`):
+### AI 生成的变更增量（在 `openspec/changes/add-2fa/specs/auth/spec.md` 中创建）：
```markdown
-# Delta for Auth
+# 身份验证增量
-## ADDED Requirements
-### Requirement: Two-Factor Authentication
-The system MUST require a second factor during login.
+## 添加的需求
+### 需求：双因素身份验证
+系统必须在登录期间要求第二因素。
-#### Scenario: OTP required
-- WHEN a user submits valid credentials
-- THEN an OTP challenge is required
+#### 场景：需要 OTP
+- 当用户提交有效凭据时
+- 则需要 OTP 挑战
```
-### AI-Generated Tasks (created in `openspec/changes/add-2fa/tasks.md`):
+### AI 生成的任务（在 `openspec/changes/add-2fa/tasks.md` 中创建）：
```markdown
-## 1. Database Setup
-- [ ] 1.1 Add OTP secret column to users table
-- [ ] 1.2 Create OTP verification logs table
-
-## 2. Backend Implementation
-- [ ] 2.1 Add OTP generation endpoint
-- [ ] 2.2 Modify login flow to require OTP
-- [ ] 2.3 Add OTP verification endpoint
-
-## 3. Frontend Updates
-- [ ] 3.1 Create OTP input component
-- [ ] 3.2 Update login flow UI
+## 1. 数据库设置
+- [ ] 1.1 向用户表添加 OTP 密钥列
+- [ ] 1.2 创建 OTP 验证日志表
+
+## 2. 后端实施
+- [ ] 2.1 添加 OTP 生成端点
+- [ ] 2.2 修改登录流程以要求 OTP
+- [ ] 2.3 添加 OTP 验证端点
+
+## 3. 前端更新
+- [ ] 3.1 创建 OTP 输入组件
+- [ ] 3.2 更新登录流程 UI
```
-**Important:** You don't create these files manually. Your AI assistant generates them based on your requirements and the existing codebase.
+**重要提示：** 您不需要手动创建这些文件。您的 AI 助手会根据您的需求和现有代码库生成它们。
-## Understanding OpenSpec Files
+## 理解 OpenSpec 文件
-### Delta Format
+### 增量格式
-Deltas are "patches" that show how specs change:
+增量是显示规范如何变化的"补丁"：
-- **`## ADDED Requirements`** - New capabilities
-- **`## MODIFIED Requirements`** - Changed behavior (include complete updated text)
-- **`## REMOVED Requirements`** - Deprecated features
+- **`## ADDED Requirements`** - 新功能
+- **`## MODIFIED Requirements`** - 更改的行为（包括完整的更新文本）
+- **`## REMOVED Requirements`** - 已弃用的功能
-**Format requirements:**
-- Use `### Requirement: ` for headers
-- Every requirement needs at least one `#### Scenario:` block
-- Use SHALL/MUST in requirement text
+**格式要求：**
+- 使用 `### Requirement: ` 作为标题
+- 每个需求至少需要一个 `#### Scenario:` 块
+- 在需求文本中使用 SHALL/MUST
-## How OpenSpec Compares
+## OpenSpec 的比较详细说明
-### vs. spec-kit
-OpenSpec’s two-folder model (`openspec/specs/` for the current truth, `openspec/changes/` for proposed updates) keeps state and diffs separate. This scales when you modify existing features or touch multiple specs. spec-kit is strong for greenfield/0→1 but provides less structure for cross-spec updates and evolving features.
+### 与 spec-kit 的比较
+OpenSpec 的双文件夹模型（`openspec/specs/` 用于当前真实状态，`openspec/changes/` 用于提议的更新）将状态和差异分开。当您修改现有功能或触及多个规范时，这种方式可以扩展。spec-kit 在全新/0→1 方面表现强劲，但在跨规范更新和演进功能方面提供的结构较少。
-### vs. Kiro.dev
-OpenSpec groups every change for a feature in one folder (`openspec/changes/feature-name/`), making it easy to track related specs, tasks, and designs together. Kiro spreads updates across multiple spec folders, which can make feature tracking harder.
+### 与 Kiro.dev 的比较
+OpenSpec 将功能的每个变更分组在一个文件夹中（`openspec/changes/feature-name/`），使得跟踪相关的规范、任务和设计变得容易。Kiro 将更新分散在多个规范文件夹中，这可能使功能跟踪变得更加困难。
-### vs. No Specs
-Without specs, AI coding assistants generate code from vague prompts, often missing requirements or adding unwanted features. OpenSpec brings predictability by agreeing on the desired behavior before any code is written.
+### 与无规范的比较
+没有规范，AI 编码助手会根据模糊的提示生成代码，经常遗漏需求或添加不需要的功能。OpenSpec 通过在编写任何代码之前就所需行为达成一致来带来可预测性。
-## Team Adoption
+## 团队采用
-1. **Initialize OpenSpec** – Run `openspec init` in your repo.
-2. **Start with new features** – Ask your AI to capture upcoming work as change proposals.
-3. **Grow incrementally** – Each change archives into living specs that document your system.
-4. **Stay flexible** – Different teammates can use Claude Code, CodeBuddy, Cursor, or any AGENTS.md-compatible tool while sharing the same specs.
+1. **初始化 OpenSpec** – 在您的仓库中运行 `openspec init`。
+2. **从新功能开始** – 要求您的 AI 将即将进行的工作捕获为变更提案。
+3. **逐步增长** – 每个变更都归档到记录您系统的活动规范中。
+4. **保持灵活性** – 不同的团队成员可以使用 Claude Code、CodeBuddy、Cursor 或任何兼容 AGENTS.md 的工具，同时共享相同的规范。
-Run `openspec update` whenever someone switches tools so your agents pick up the latest instructions and slash-command bindings.
+每当有人切换工具时运行 `openspec update`，以便您的代理获取最新的指令和斜杠命令绑定。
-## Updating OpenSpec
+## 更新 OpenSpec
-1. **Upgrade the package**
+1. **升级包**
```bash
npm install -g @fission-ai/openspec@latest
```
-2. **Refresh agent instructions**
- - Run `openspec update` inside each project to regenerate AI guidance and ensure the latest slash commands are active.
+2. **刷新代理指令**
+ - 在每个项目中运行 `openspec update` 以重新生成 AI 指导并确保最新的斜杠命令处于活动状态。
-## Contributing
+## 贡献
-- Install dependencies: `pnpm install`
-- Build: `pnpm run build`
-- Test: `pnpm test`
-- Develop CLI locally: `pnpm run dev` or `pnpm run dev:cli`
-- Conventional commits (one-line): `type(scope): subject`
+- 安装依赖项：`pnpm install`
+- 构建：`pnpm run build`
+- 测试：`pnpm test`
+- 本地开发 CLI：`pnpm run dev` 或 `pnpm run dev:cli`
+- 约定式提交（单行）：`type(scope): subject`
-## License
+## 许可证
MIT
diff --git a/README.zh-CN.md b/README.zh-CN.md
new file mode 100644
index 00000000..29273336
--- /dev/null
+++ b/README.zh-CN.md
@@ -0,0 +1,382 @@
+
+
+
+
+
+ 
+
+
+
+
+为 AI 编码助手提供规范驱动的开发方式。
+
+
+
+ 
+ 
+ 
+ 
+
+
+
+ 
+
+
+
+ 在 X 上关注 @0xTab 获取更新 · 加入 OpenSpec Discord 寻求帮助和提问。
+
+
+> [English Version](README.md)
+
+# OpenSpec
+
+OpenSpec 通过规范驱动的开发方式，让人类和 AI 编码助手在编写任何代码之前就对要构建的内容达成一致。**无需 API 密钥。**
+
+## 为什么选择 OpenSpec？
+
+AI 编码助手功能强大，但当需求存在于聊天历史中时，它们的行为是不可预测的。OpenSpec 添加了一个轻量级的规范工作流，在实施之前锁定意图，为您提供确定性的、可审查的输出。
+
+主要成果：
+- 人类和 AI 利益相关者在工作开始前就规范达成一致。
+- 结构化的变更文件夹（提案、任务和规范更新）使范围明确且可审计。
+- 对提议的、活跃的或已归档的内容具有共享可见性。
+- 与您已经使用的 AI 工具配合使用：在支持的地方使用自定义斜杠命令，在其他地方使用上下文规则。
+
+## OpenSpec 的比较（概览）
+
+- **轻量级**：简单的工作流程，无需 API 密钥，最小化设置。
+- **优先支持现有项目**：不仅适用于从零开始的项目。OpenSpec 将真实来源与提案分离：`openspec/specs/`（当前真实状态）和 `openspec/changes/`（提议的更新）。这使得跨功能的差异保持明确和可管理。
+- **变更跟踪**：提案、任务和规范增量放在一起；归档将批准的更新合并回规范。
+- **与 spec-kit 和 Kiro 的比较**：这些工具在全新功能（0→1）方面表现出色。OpenSpec 在修改现有行为（1→n）时也很出色，特别是当更新跨越多个规范时。
+
+查看 [OpenSpec 的比较](#openspec-的比较详细说明) 了解完整对比。
+
+## 工作原理
+
+```
+┌────────────────────┐
+│ 起草变更提案 │
+│ │
+└────────┬───────────┘
+ │ 与您的 AI 分享意图
+ ▼
+┌────────────────────┐
+│ 审查与对齐 │
+│ (编辑规范/任务) │◀──── 反馈循环 ──────┐
+└────────┬───────────┘ │
+ │ 批准的计划 │
+ ▼ │
+┌────────────────────┐ │
+│ 实施任务 │──────────────────────┘
+│ (AI 编写代码) │
+└────────┬───────────┘
+ │ 发布变更
+ ▼
+┌────────────────────┐
+│ 归档并更新 │
+│ 规范（源） │
+└────────────────────┘
+
+1. 起草一个变更提案，捕获您想要的规范更新。
+2. 与您的 AI 助手一起审查提案，直到每个人都同意。
+3. 实施引用已同意规范的任务。
+4. 归档变更，将批准的更新合并回真实来源规范。
+```
+
+## 入门指南
+
+### 支持的 AI 工具
+
+
+原生斜杠命令（点击展开）
+
+这些工具具有内置的 OpenSpec 命令。在提示时选择 OpenSpec 集成。
+
+| 工具 | 命令 |
+|------|----------|
+| **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` (`.amazonq/prompts/`) |
+| **Antigravity** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.agent/workflows/`) |
+| **Auggie (Augment CLI)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.augment/commands/`) |
+| **Claude Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` |
+| **Cline** | `.clinerules/workflows/` 目录中的工作流 (`.clinerules/workflows/openspec-*.md`) |
+| **CodeBuddy Code (CLI)** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.codebuddy/commands/`) — 查看 [文档](https://www.codebuddy.ai/cli) |
+| **Codex** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (全局: `~/.codex/prompts`, 自动安装) |
+| **CoStrict** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.cospec/openspec/commands/`) — 查看 [文档](https://costrict.ai)|
+| **Crush** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.crush/commands/openspec/`) |
+| **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
+| **Factory Droid** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.factory/commands/`) |
+| **Gemini CLI** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.gemini/commands/openspec/`) |
+| **GitHub Copilot** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.github/prompts/`) |
+| **iFlow (iflow-cli)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.iflow/commands/`) |
+| **Kilo Code** | `/openspec-proposal.md`, `/openspec-apply.md`, `/openspec-archive.md` (`.kilocode/workflows/`) |
+| **OpenCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
+| **Qoder (CLI)** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.qoder/commands/openspec/`) — 查看 [文档](https://qoder.com/cli) |
+| **Qwen Code** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.qwen/commands/`) |
+| **RooCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.roo/commands/`) |
+| **Windsurf** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.windsurf/workflows/`) |
+
+Kilo Code 自动发现团队工作流。将生成的文件保存在 `.kilocode/workflows/` 下，并使用 `/openspec-proposal.md`、`/openspec-apply.md` 或 `/openspec-archive.md` 从命令面板触发它们。
+
+
+
+
+兼容 AGENTS.md（点击展开）
+
+这些工具会自动从 `openspec/AGENTS.md` 读取工作流指令。如果它们需要提醒，请要求它们遵循 OpenSpec 工作流。了解更多关于 [AGENTS.md 约定](https://agents.md/)。
+
+| 工具 |
+|-------|
+| Amp • Jules • 其他 |
+
+
+
+### 安装与初始化
+
+#### 前提条件
+- **Node.js >= 20.19.0** - 使用 `node --version` 检查您的版本
+
+#### 步骤 1：全局安装 CLI
+
+```bash
+npm install -g @fission-ai/openspec@latest
+```
+
+验证安装：
+```bash
+openspec --version
+```
+
+#### 步骤 2：在您的项目中初始化 OpenSpec
+
+导航到您的项目目录：
+```bash
+cd my-project
+```
+
+运行初始化：
+```bash
+openspec init
+```
+
+**初始化期间会发生什么：**
+- 系统会提示您选择任何原生支持的 AI 工具（Claude Code、CodeBuddy、Cursor、OpenCode、Qoder 等）；其他助手始终依赖共享的 `AGENTS.md` 存根
+- OpenSpec 会自动为您选择的工具配置斜杠命令，并始终在项目根目录编写一个托管的 `AGENTS.md` 交接文件
+- 在您的项目中创建一个新的 `openspec/` 目录结构
+
+**设置后：**
+- 主要的 AI 工具可以在不需要额外配置的情况下触发 `/openspec` 工作流
+- 运行 `openspec list` 以验证设置并查看任何活跃的变更
+- 如果您的编码助手没有立即显示新的斜杠命令，请重新启动它。斜杠命令在启动时加载，因此重新启动可确保它们出现
+
+### 可选：填充项目上下文
+
+`openspec init` 完成后，您将收到一个建议的提示，以帮助填充您的项目上下文：
+
+```text
+填充您的项目上下文：
+"请阅读 openspec/project.md 并帮我填写有关我的项目、技术栈和约定的详细信息"
+```
+
+使用 `openspec/project.md` 定义项目级别的约定、标准、架构模式和其他应在所有变更中遵循的指南。
+
+### 创建您的第一个变更
+
+这是一个展示完整 OpenSpec 工作流的真实示例。这适用于任何 AI 工具。具有原生斜杠命令的工具将自动识别快捷方式。
+
+#### 1. 起草提案
+首先要求您的 AI 创建一个变更提案：
+
+```text
+您：为按角色和团队添加个人资料搜索过滤器创建一个 OpenSpec 变更提案
+ （具有斜杠命令的工具的快捷方式：/openspec:proposal 添加个人资料搜索过滤器）
+
+AI：我将为个人资料过滤器创建一个 OpenSpec 变更提案。
+ *使用 proposal.md、tasks.md、规范增量搭建 openspec/changes/add-profile-filters/。*
+```
+
+#### 2. 验证与审查
+检查变更是否正确创建并审查提案：
+
+```bash
+$ openspec list # 确认变更文件夹存在
+$ openspec validate add-profile-filters # 验证规范格式
+$ openspec show add-profile-filters # 审查提案、任务和规范增量
+```
+
+#### 3. 完善规范
+迭代规范，直到它们符合您的需求：
+
+```text
+您：您能为角色和团队过滤器添加验收标准吗？
+
+AI：我将使用角色和团队过滤器的场景更新规范增量。
+ *编辑 openspec/changes/add-profile-filters/specs/profile/spec.md 和 tasks.md。*
+```
+
+#### 4. 实施变更
+一旦规范看起来不错，开始实施：
+
+```text
+您：规范看起来不错。让我们实施这个变更。
+ （具有斜杠命令的工具的快捷方式：/openspec:apply add-profile-filters）
+
+AI：我将完成 add-profile-filters 变更中的任务。
+ *从 openspec/changes/add-profile-filters/tasks.md 实施任务*
+ *标记任务完成：任务 1.1 ✓，任务 1.2 ✓，任务 2.1 ✓...*
+```
+
+#### 5. 归档已完成的变更
+实施完成后，归档变更：
+
+```text
+AI：所有任务都已完成。实施已准备就绪。
+
+您：请归档变更
+ （具有斜杠命令的工具的快捷方式：/openspec:archive add-profile-filters）
+
+AI：我将归档 add-profile-filters 变更。
+ *运行：openspec archive add-profile-filters --yes*
+ ✓ 变更已成功归档。规范已更新。准备好下一个功能！
+```
+
+或者在终端中自己运行命令：
+```bash
+$ openspec archive add-profile-filters --yes # 无提示归档已完成的变更
+```
+
+**注意：** 具有原生斜杠命令的工具（Claude Code、CodeBuddy、Cursor、Codex、Qoder、RooCode）可以使用显示的快捷方式。所有其他工具都使用自然语言请求"创建 OpenSpec 提案"、"应用 OpenSpec 变更"或"归档变更"。
+
+## 命令参考
+
+```bash
+openspec list # 查看活跃的变更文件夹
+openspec view # 规范和变更的交互式仪表板
+openspec show # 显示变更详细信息（提案、任务、规范更新）
+openspec validate # 检查规范格式和结构
+openspec archive [--yes|-y] # 将已完成的变更移动到 archive/（使用 --yes 进行非交互式操作）
+```
+
+## 示例：AI 如何创建 OpenSpec 文件
+
+当您要求 AI 助手"添加双因素身份验证"时，它会创建：
+
+```
+openspec/
+├── specs/
+│ └── auth/
+│ └── spec.md # 当前的身份验证规范（如果存在）
+└── changes/
+ └── add-2fa/ # AI 创建整个结构
+ ├── proposal.md # 为什么以及什么变更
+ ├── tasks.md # 实施清单
+ ├── design.md # 技术决策（可选）
+ └── specs/
+ └── auth/
+ └── spec.md # 显示添加内容的增量
+```
+
+### AI 生成的规范（在 `openspec/specs/auth/spec.md` 中创建）：
+
+```markdown
+# 身份验证规范
+
+## 目的
+身份验证和会话管理。
+
+## 需求
+### 需求：用户身份验证
+系统应在成功登录时发出 JWT。
+
+#### 场景：有效凭据
+- 当用户提交有效凭据时
+- 则返回 JWT
+```
+
+### AI 生成的变更增量（在 `openspec/changes/add-2fa/specs/auth/spec.md` 中创建）：
+
+```markdown
+# 身份验证增量
+
+## 添加的需求
+### 需求：双因素身份验证
+系统必须在登录期间要求第二因素。
+
+#### 场景：需要 OTP
+- 当用户提交有效凭据时
+- 则需要 OTP 挑战
+```
+
+### AI 生成的任务（在 `openspec/changes/add-2fa/tasks.md` 中创建）：
+
+```markdown
+## 1. 数据库设置
+- [ ] 1.1 向用户表添加 OTP 密钥列
+- [ ] 1.2 创建 OTP 验证日志表
+
+## 2. 后端实施
+- [ ] 2.1 添加 OTP 生成端点
+- [ ] 2.2 修改登录流程以要求 OTP
+- [ ] 2.3 添加 OTP 验证端点
+
+## 3. 前端更新
+- [ ] 3.1 创建 OTP 输入组件
+- [ ] 3.2 更新登录流程 UI
+```
+
+**重要提示：** 您不需要手动创建这些文件。您的 AI 助手会根据您的需求和现有代码库生成它们。
+
+## 理解 OpenSpec 文件
+
+### 增量格式
+
+增量是显示规范如何变化的"补丁"：
+
+- **`## ADDED Requirements`** - 新功能
+- **`## MODIFIED Requirements`** - 更改的行为（包括完整的更新文本）
+- **`## REMOVED Requirements`** - 已弃用的功能
+
+**格式要求：**
+- 使用 `### Requirement: ` 作为标题
+- 每个需求至少需要一个 `#### Scenario:` 块
+- 在需求文本中使用 SHALL/MUST
+
+## OpenSpec 的比较详细说明
+
+### 与 spec-kit 的比较
+OpenSpec 的双文件夹模型（`openspec/specs/` 用于当前真实状态，`openspec/changes/` 用于提议的更新）将状态和差异分开。当您修改现有功能或触及多个规范时，这种方式可以扩展。spec-kit 在全新/0→1 方面表现强劲，但在跨规范更新和演进功能方面提供的结构较少。
+
+### 与 Kiro.dev 的比较
+OpenSpec 将功能的每个变更分组在一个文件夹中（`openspec/changes/feature-name/`），使得跟踪相关的规范、任务和设计变得容易。Kiro 将更新分散在多个规范文件夹中，这可能使功能跟踪变得更加困难。
+
+### 与无规范的比较
+没有规范，AI 编码助手会根据模糊的提示生成代码，经常遗漏需求或添加不需要的功能。OpenSpec 通过在编写任何代码之前就所需行为达成一致来带来可预测性。
+
+## 团队采用
+
+1. **初始化 OpenSpec** – 在您的仓库中运行 `openspec init`。
+2. **从新功能开始** – 要求您的 AI 将即将进行的工作捕获为变更提案。
+3. **逐步增长** – 每个变更都归档到记录您系统的活动规范中。
+4. **保持灵活性** – 不同的团队成员可以使用 Claude Code、CodeBuddy、Cursor 或任何兼容 AGENTS.md 的工具，同时共享相同的规范。
+
+每当有人切换工具时运行 `openspec update`，以便您的代理获取最新的指令和斜杠命令绑定。
+
+## 更新 OpenSpec
+
+1. **升级包**
+ ```bash
+ npm install -g @fission-ai/openspec@latest
+ ```
+2. **刷新代理指令**
+ - 在每个项目中运行 `openspec update` 以重新生成 AI 指导并确保最新的斜杠命令处于活动状态。
+
+## 贡献
+
+- 安装依赖项：`pnpm install`
+- 构建：`pnpm run build`
+- 测试：`pnpm test`
+- 本地开发 CLI：`pnpm run dev` 或 `pnpm run dev:cli`
+- 约定式提交（单行）：`type(scope): subject`
+
+## 许可证
+
+MIT
diff --git a/docs/artifact_poc.md b/docs/artifact_poc.md
index 01dd0098..f1eb240f 100644
--- a/docs/artifact_poc.md
+++ b/docs/artifact_poc.md
@@ -1,128 +1,130 @@
-# POC-OpenSpec-Core Analysis
+# POC-OpenSpec-Core 分析
+
+> [English Version](artifact_poc.md)
---
-## Design Decisions & Terminology
+## 设计决策与术语
-### Philosophy: Not a Workflow System
+### 理念：不是工作流系统
-This system is **not** a workflow engine. It's an **artifact tracker with dependency awareness**.
+该系统**不是**工作流引擎。它是一个**具有依赖关系感知的工件跟踪器**。
-| What it's NOT | What it IS |
+| 它不是什么 | 它是什么 |
|---------------|------------|
-| Linear step-by-step progression | Exploratory, iterative planning |
-| Bureaucratic checkpoints | Enablers that unlock possibilities |
-| "You must complete step 1 first" | "Here's what you could create now" |
-| Form-filling | Fluid document creation |
+| 线性的逐步进展 | 探索性的、迭代的规划 |
+| 官僚式的检查点 | 解锁可能性的启用器 |
+| "您必须先完成步骤 1" | "这是您现在可以创建的内容" |
+| 填表 | 流畅的文档创建 |
-**Key insight:** Dependencies are *enablers*, not *gates*. You can't meaningfully write a design document if there's no proposal to design from - that's not bureaucracy, it's logic.
+**关键见解：** 依赖关系是*启用器*，而不是*门槛*。如果没有提案可供设计，您就无法有意义地编写设计文档 - 这不是官僚主义，这是逻辑。
-### Terminology
+### 术语
-| Term | Definition | Example |
+| 术语 | 定义 | 示例 |
|------|------------|---------|
-| **Change** | A unit of work being planned (feature, refactor, migration) | `openspec/changes/add-auth/` |
-| **Schema** | An artifact graph definition (what artifacts exist, their dependencies) | `spec-driven.yaml` |
-| **Artifact** | A node in the graph (a document to create) | `proposal`, `design`, `specs` |
-| **Template** | Instructions/guidance for creating an artifact | `templates/proposal.md` |
+| **Change** | 正在规划的工作单元（功能、重构、迁移） | `openspec/changes/add-auth/` |
+| **Schema** | 工件图定义（存在哪些工件，它们的依赖关系） | `spec-driven.yaml` |
+| **Artifact** | 图中的节点（要创建的文档） | `proposal`、`design`、`specs` |
+| **Template** | 创建工件的指令/指导 | `templates/proposal.md` |
-### Hierarchy
+### 层次结构
```
-Schema (defines) ──→ Artifacts (guided by) ──→ Templates
+Schema (定义) ──→ Artifacts (指导) ──→ Templates
```
-- **Schema** = the artifact graph (what exists, dependencies)
-- **Artifact** = a document to produce
-- **Template** = instructions for creating that artifact
+- **Schema** = 工件图（存在什么，依赖关系）
+- **Artifact** = 要生成的文档
+- **Template** = 创建该工件的指令
-### Schema Variations
+### Schema 变体
-Schemas can vary across multiple dimensions:
+Schema 可以在多个维度上变化：
-| Dimension | Examples |
+| 维度 | 示例 |
|-----------|----------|
-| Philosophy | `spec-driven`, `tdd`, `prototype-first` |
-| Version | `v1`, `v2`, `v3` |
-| Language | `en`, `zh`, `es` |
-| Custom | `team-alpha`, `experimental` |
+| 理念 | `spec-driven`、`tdd`、`prototype-first` |
+| 版本 | `v1`、`v2`、`v3` |
+| 语言 | `en`、`zh`、`es` |
+| 自定义 | `team-alpha`、`experimental` |
-### Schema Resolution (XDG Standard)
+### Schema 解析（XDG 标准）
-Schemas follow the XDG Base Directory Specification with a 2-level resolution:
+Schema 遵循 XDG 基本目录规范，具有 2 级解析：
```
-1. ${XDG_DATA_HOME}/openspec/schemas//schema.yaml # Global user override
-2. /schemas//schema.yaml # Built-in defaults
+1. ${XDG_DATA_HOME}/openspec/schemas//schema.yaml # 全局用户覆盖
+2. /schemas//schema.yaml # 内置默认值
```
-**Platform-specific paths:**
-- Unix/macOS: `~/.local/share/openspec/schemas/`
-- Windows: `%LOCALAPPDATA%/openspec/schemas/`
-- All platforms: `$XDG_DATA_HOME/openspec/schemas/` (when set)
+**特定平台路径：**
+- Unix/macOS：`~/.local/share/openspec/schemas/`
+- Windows：`%LOCALAPPDATA%/openspec/schemas/`
+- 所有平台：`$XDG_DATA_HOME/openspec/schemas/`（设置时）
-**Why XDG?**
-- Schemas are workflow definitions (data), not user preferences (config)
-- Built-ins baked into package, never auto-copied
-- Users customize by creating files in global data dir
-- Consistent with modern CLI tooling standards
+**为什么使用 XDG？**
+- Schema 是工作流定义（数据），而不是用户偏好（配置）
+- 内置的烘焙到包中，从不自动复制
+- 用户通过在全局数据目录中创建文件来自定义
+- 与现代 CLI 工具标准一致
-### Template Inheritance (2 Levels Max)
+### 模板继承（最多 2 级）
-Templates are co-located with schemas in a `templates/` subdirectory:
+模板与 schema 共同位于 `templates/` 子目录中：
```
-1. ${XDG_DATA_HOME}/openspec/schemas//templates/.md # User override
-2. /schemas//templates/.md # Built-in
+1. ${XDG_DATA_HOME}/openspec/schemas//templates/.md # 用户覆盖
+2. /schemas//templates/.md # 内置
```
-**Rules:**
-- User overrides take precedence over package built-ins
-- A CLI command shows resolved paths (no guessing)
-- No inheritance between schemas (copy if you need to diverge)
-- Templates are always co-located with their schema
+**规则：**
+- 用户覆盖优先于包内置
+- CLI 命令显示解析的路径（无需猜测）
+- schema 之间没有继承（如果需要分歧，请复制）
+- 模板始终与其 schema 共同位于
-**Why this matters:**
-- Avoids "where does this come from?" debugging
-- No implicit magic that works until it doesn't
-- Schema + templates form a cohesive unit
+**为什么这很重要：**
+- 避免"这来自哪里？"的调试
+- 没有隐式魔法，直到它不起作用
+- Schema + 模板形成一个有凝聚力的单元
---
-## Executive Summary
+## 执行摘要
-This is an **artifact tracker with dependency awareness** that guides iterative development through a structured artifact pipeline. The core innovation is using the **filesystem as a database** - artifact completion is detected by file existence, making the system stateless and version-control friendly.
+这是一个**具有依赖关系感知的工件跟踪器**，通过结构化的工件管道指导迭代开发。核心创新是使用**文件系统作为数据库** - 工件完成由文件存在检测，使系统无状态且版本控制友好。
-The system answers:
-- "What artifacts exist for this change?"
-- "What could I create next?" (not "what must I create")
-- "What's blocking X?" (informational, not prescriptive)
+系统回答：
+- "此变更存在哪些工件？"
+- "我接下来可以创建什么？"（不是"我必须创建什么"）
+- "什么阻止了 X？"（信息性的，而不是规定性的）
---
-## Core Components
+## 核心组件
-### 1. ArtifactGraph (Slice 1 - COMPLETE)
+### 1. ArtifactGraph（切片 1 - 完成）
-The dependency graph engine with XDG-compliant schema resolution.
+具有 XDG 兼容 schema 解析的依赖图引擎。
-| Responsibility | Approach |
+| 职责 | 方法 |
|----------------|----------|
-| Model artifacts as a DAG | Artifact with `requires: string[]` |
-| Track completion state | `Set` for completed artifacts |
-| Calculate build order | Kahn's algorithm (topological sort) |
-| Find ready artifacts | Check if all dependencies are in `completed` set |
-| Resolve schemas | XDG global → package built-ins |
+| 将工件建模为 DAG | 具有 `requires: string[]` 的 Artifact |
+| 跟踪完成状态 | 已完成工件的 `Set` |
+| 计算构建顺序 | Kahn 算法（拓扑排序） |
+| 查找就绪工件 | 检查所有依赖项是否在 `completed` 集合中 |
+| 解析 schema | XDG 全局 → 包内置 |
-**Key Data Structures (Zod-validated):**
+**关键数据结构（Zod 验证）：**
```typescript
-// Zod schemas define types + validation
+// Zod schema 定义类型 + 验证
const ArtifactSchema = z.object({
id: z.string().min(1),
- generates: z.string().min(1), // e.g., "proposal.md" or "specs/*.md"
+ generates: z.string().min(1), // 例如 "proposal.md" 或 "specs/*.md"
description: z.string(),
- template: z.string(), // path to template file
+ template: z.string(), // 模板文件路径
requires: z.array(z.string()).default([]),
});
@@ -133,56 +135,56 @@ const SchemaYamlSchema = z.object({
artifacts: z.array(ArtifactSchema).min(1),
});
-// Derived types
+// 派生类型
type Artifact = z.infer;
type SchemaYaml = z.infer;
```
-**Key Methods:**
-- `resolveSchema(name)` - Load schema with XDG fallback
-- `ArtifactGraph.fromSchema(schema)` - Build graph from schema
-- `detectState(graph, changeDir)` - Scan filesystem for completion
-- `getNextArtifacts(graph, completed)` - Find artifacts ready to create
-- `getBuildOrder(graph)` - Topological sort of all artifacts
-- `getBlocked(graph, completed)` - Artifacts with unmet dependencies
+**关键方法：**
+- `resolveSchema(name)` - 使用 XDG 回退加载 schema
+- `ArtifactGraph.fromSchema(schema)` - 从 schema 构建图
+- `detectState(graph, changeDir)` - 扫描文件系统以完成
+- `getNextArtifacts(graph, completed)` - 查找准备创建的工件
+- `getBuildOrder(graph)` - 所有工件的拓扑排序
+- `getBlocked(graph, completed)` - 具有未满足依赖项的工件
---
-### 2. Change Utilities (Slice 2)
+### 2. Change 实用程序（切片 2）
-Simple utility functions for programmatic change creation. No class, no abstraction layer.
+用于程序化变更创建的简单实用函数。没有类，没有抽象层。
-| Responsibility | Approach |
+| 职责 | 方法 |
|----------------|----------|
-| Create changes | Create dirs under `openspec/changes//` with README |
-| Name validation | Enforce kebab-case naming |
+| 创建变更 | 在 `openspec/changes//` 下创建目录并附带 README |
+| 名称验证 | 强制执行 kebab-case 命名 |
-**Key Paths:**
+**关键路径：**
```
-openspec/changes// → Change instances with artifacts (project-level)
+openspec/changes// → 具有工件的变更实例（项目级别）
```
-**Key Functions** (`src/utils/change-utils.ts`):
-- `createChange(projectRoot, name, description?)` - Create new change directory + README
-- `validateChangeName(name)` - Validate kebab-case naming, returns `{ valid, error? }`
+**关键函数**（`src/utils/change-utils.ts`）：
+- `createChange(projectRoot, name, description?)` - 创建新的变更目录 + README
+- `validateChangeName(name)` - 验证 kebab-case 命名，返回 `{ valid, error? }`
-**Note:** Existing CLI commands (`ListCommand`, `ChangeCommand`) already handle listing, path resolution, and existence checks. No need to extract that logic - it works fine as-is.
+**注意：** 现有的 CLI 命令（`ListCommand`、`ChangeCommand`）已经处理列表、路径解析和存在性检查。无需提取该逻辑 - 它按原样工作正常。
---
-### 3. InstructionLoader (Slice 3)
+### 3. InstructionLoader（切片 3）
-Template resolution and instruction enrichment.
+模板解析和指令丰富。
-| Responsibility | Approach |
+| 职责 | 方法 |
|----------------|----------|
-| Resolve templates | XDG 2-level fallback (schema-specific → shared → built-in) |
-| Build dynamic context | Gather dependency status, change info |
-| Enrich templates | Inject context into base templates |
-| Generate status reports | Formatted markdown with progress |
+| 解析模板 | XDG 2 级回退（特定于 schema → 共享 → 内置） |
+| 构建动态上下文 | 收集依赖状态、变更信息 |
+| 丰富模板 | 将上下文注入基础模板 |
+| 生成状态报告 | 带有进度的格式化 markdown |
-**Key Class - ChangeState:**
+**关键类 - ChangeState：**
```
ChangeState {
@@ -191,74 +193,74 @@ ChangeState {
graph: ArtifactGraph
completed: Set
- // Methods
+ // 方法
getNextSteps(): string[]
getStatus(artifactId): ArtifactStatus
isComplete(): boolean
}
```
-**Key Functions:**
-- `getTemplatePath(artifactId, schemaName?)` - Resolve with 2-level fallback
-- `getEnrichedInstructions(artifactId, projectRoot, changeName?)` - Main entry point
-- `getChangeStatus(projectRoot, changeName?)` - Formatted status report
+**关键函数：**
+- `getTemplatePath(artifactId, schemaName?)` - 使用 2 级回退解析
+- `getEnrichedInstructions(artifactId, projectRoot, changeName?)` - 主入口点
+- `getChangeStatus(projectRoot, changeName?)` - 格式化状态报告
---
-### 4. CLI (Slice 4)
+### 4. CLI（切片 4）
-User interface layer. **All commands are deterministic** - require explicit `--change` parameter.
+用户界面层。**所有命令都是确定性的** - 需要显式的 `--change` 参数。
-| Command | Function | Status |
+| 命令 | 功能 | 状态 |
|---------|----------|--------|
-| `status --change ` | Show change progress (artifact graph) | **NEW** |
-| `next --change ` | Show artifacts ready to create | **NEW** |
-| `instructions --change ` | Get enriched instructions for artifact | **NEW** |
-| `list` | List all changes | EXISTS (`openspec change list`) |
-| `new ` | Create change | **NEW** (uses `createChange()`) |
-| `init` | Initialize structure | EXISTS (`openspec init`) |
-| `templates --change ` | Show resolved template paths | **NEW** |
+| `status --change ` | 显示变更进度（工件图） | **新** |
+| `next --change ` | 显示准备创建的工件 | **新** |
+| `instructions --change ` | 获取工件的丰富指令 | **新** |
+| `list` | 列出所有变更 | 存在（`openspec change list`） |
+| `new ` | 创建变更 | **新**（使用 `createChange()`） |
+| `init` | 初始化结构 | 存在（`openspec init`） |
+| `templates --change ` | 显示解析的模板路径 | **新** |
-**Note:** Commands that operate on a change require `--change`. Missing parameter → error with list of available changes. Agent infers the change from conversation and passes it explicitly.
+**注意：** 对变更进行操作的命令需要 `--change`。缺少参数 → 错误，并显示可用变更列表。代理从对话中推断变更并明确传递它。
-**Existing CLI commands** (not part of this slice):
+**现有的 CLI 命令**（不属于此切片）：
- `openspec change list` / `openspec change show ` / `openspec change validate `
- `openspec list --changes` / `openspec list --specs`
-- `openspec view` (dashboard)
+- `openspec view`（仪表板）
- `openspec init` / `openspec archive `
---
-### 5. Claude Commands
+### 5. Claude 命令
-Integration layer for Claude Code. **Operational commands only** - artifact creation via natural language.
+Claude Code 的集成层。**仅操作命令** - 通过自然语言创建工件。
-| Command | Purpose |
+| 命令 | 目的 |
|---------|---------|
-| `/status` | Show change progress |
-| `/next` | Show what's ready to create |
-| `/run [artifact]` | Execute a specific step (power users) |
-| `/list` | List all changes |
-| `/new ` | Create a new change |
-| `/init` | Initialize structure |
+| `/status` | 显示变更进度 |
+| `/next` | 显示准备创建的内容 |
+| `/run [artifact]` | 执行特定步骤（高级用户） |
+| `/list` | 列出所有变更 |
+| `/new ` | 创建新变更 |
+| `/init` | 初始化结构 |
-**Artifact creation:** Users say "create the proposal" or "write the tests" in natural language. The agent:
-1. Infers change from conversation (confirms if uncertain)
-2. Infers artifact from request
-3. Calls CLI with explicit `--change` parameter
-4. Creates artifact following instructions
+**工件创建：** 用户用自然语言说"创建提案"或"编写测试"。代理：
+1. 从对话中推断变更（如果不确定则确认）
+2. 从请求中推断工件
+3. 使用显式的 `--change` 参数调用 CLI
+4. 按照指令创建工件
-This works for ANY artifact in ANY schema - no new slash commands needed when schemas change.
+这适用于任何 schema 中的任何工件 - 当 schema 更改时不需要新的斜杠命令。
-**Note:** Legacy commands (`/openspec-proposal`, `/openspec-apply`, `/openspec-archive`) exist in the main project for backward compatibility but are separate from this architecture.
+**注意：** 遗留命令（`/openspec-proposal`、`/openspec-apply`、`/openspec-archive`）存在于主项目中以实现向后兼容性，但与此架构分离。
---
-## Component Dependency Graph
+## 组件依赖图
```
┌─────────────────────────────────────────────────────────────┐
-│ PRESENTATION LAYER │
+│ 表示层 │
│ ┌──────────────┐ ┌────────────────────┐ │
│ │ CLI │ ←─shell exec───────│ Claude Commands │ │
│ └──────┬───────┘ └────────────────────┘ │
@@ -266,30 +268,30 @@ This works for ANY artifact in ANY schema - no new slash commands needed when sc
│ imports
▼
┌─────────────────────────────────────────────────────────────┐
-│ ORCHESTRATION LAYER │
+│ 编排层 │
│ ┌────────────────────┐ ┌──────────────────────────┐ │
-│ │ InstructionLoader │ │ change-utils (Slice 2) │ │
-│ │ (Slice 3) │ │ createChange() │ │
+│ │ InstructionLoader │ │ change-utils (切片 2) │ │
+│ │ (切片 3) │ │ createChange() │ │
│ └─────────┬──────────┘ │ validateChangeName() │ │
│ │ └──────────────────────────┘ │
└────────────┼────────────────────────────────────────────────┘
│ uses
▼
┌─────────────────────────────────────────────────────────────┐
-│ CORE LAYER │
+│ 核心层 │
│ ┌──────────────────────────────────────────────────────┐ │
-│ │ ArtifactGraph (Slice 1) │ │
+│ │ ArtifactGraph (切片 1) │ │
│ │ │ │
-│ │ Schema Resolution (XDG) ──→ Graph ──→ State Detection│ │
+│ │ Schema 解析 (XDG) ──→ 图 ──→ 状态检测 │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
▲
│ reads from
▼
┌─────────────────────────────────────────────────────────────┐
-│ PERSISTENCE LAYER │
+│ 持久层 │
│ ┌──────────────────┐ ┌────────────────────────────────┐ │
-│ │ XDG Schemas │ │ Project Artifacts │ │
+│ │ XDG Schemas │ │ 项目工件 │ │
│ │ ~/.local/share/ │ │ openspec/changes// │ │
│ │ openspec/ │ │ - proposal.md, design.md │ │
│ │ schemas/ │ │ - specs/*.md, tasks.md │ │
@@ -299,58 +301,58 @@ This works for ANY artifact in ANY schema - no new slash commands needed when sc
---
-## Key Design Patterns
+## 关键设计模式
-### 1. Filesystem as Database
+### 1. 文件系统作为数据库
-No SQLite, no JSON state files. The existence of `proposal.md` means proposal is complete.
+没有 SQLite，没有 JSON 状态文件。`proposal.md` 的存在意味着提案已完成。
```
-// State detection is just file existence checking
+// 状态检测只是文件存在性检查
if (exists(artifactPath)) {
completed.add(artifactId)
}
```
-### 2. Deterministic CLI, Inferring Agent
+### 2. 确定性 CLI，推断代理
-**CLI layer:** Always deterministic - requires explicit `--change` parameter.
+**CLI 层：** 始终确定性 - 需要显式的 `--change` 参数。
```
-openspec status --change add-auth # explicit, works
-openspec status # error: "No change specified"
+openspec status --change add-auth # 显式，有效
+openspec status # 错误："未指定变更"
```
-**Agent layer:** Infers from conversation, confirms if uncertain, passes explicit `--change`.
+**代理层：** 从对话中推断，如果不确定则确认，传递显式的 `--change`。
-This separation means:
-- CLI is pure, testable, no state to corrupt
-- Agent handles all "smartness"
-- No config.yaml tracking of "active change"
+这种分离意味着：
+- CLI 是纯粹的、可测试的，没有要损坏的状态
+- 代理处理所有"智能"
+- 没有跟踪"活跃变更"的 config.yaml
-### 3. XDG-Compliant Schema Resolution
+### 3. XDG 兼容的 Schema 解析
```
-${XDG_DATA_HOME}/openspec/schemas//schema.yaml # User override
- ↓ (not found)
-/schemas//schema.yaml # Built-in
- ↓ (not found)
-Error (schema not found)
+${XDG_DATA_HOME}/openspec/schemas//schema.yaml # 用户覆盖
+ ↓ (未找到)
+/schemas//schema.yaml # 内置
+ ↓ (未找到)
+错误（未找到 schema）
```
-### 4. Two-Level Template Fallback
+### 4. 两级模板回退
```
-${XDG_DATA_HOME}/openspec/schemas//templates/.md # User override
- ↓ (not found)
-/schemas//templates/.md # Built-in
- ↓ (not found)
-Error (no silent fallback to avoid confusion)
+${XDG_DATA_HOME}/openspec/schemas//templates/.md # 用户覆盖
+ ↓ (未找到)
+/schemas//templates/.md # 内置
+ ↓ (未找到)
+错误（没有静默回退以避免混淆）
```
-### 5. Glob Pattern Support
+### 5. Glob 模式支持
-`specs/*.md` allows multiple files to satisfy a single artifact:
+`specs/*.md` 允许多个文件满足单个工件：
```
if (artifact.generates.includes("*")) {
@@ -361,19 +363,19 @@ if (artifact.generates.includes("*")) {
}
```
-### 6. Stateless State Detection
+### 6. 无状态状态检测
-Every command re-scans the filesystem. No cached state to corrupt.
+每个命令都重新扫描文件系统。没有要损坏的缓存状态。
---
-## Artifact Pipeline (Default Schema)
+## 工件管道（默认 Schema）
-The default `spec-driven` schema:
+默认的 `spec-driven` schema：
```
┌──────────┐
-│ proposal │ (no dependencies)
+│ proposal │ (无依赖)
└────┬─────┘
│
▼
@@ -394,112 +396,112 @@ The default `spec-driven` schema:
└──────────┘
```
-Other schemas (TDD, prototype-first) would have different graphs.
+其他 schema（TDD、prototype-first）将具有不同的图。
---
-## Implementation Order
+## 实施顺序
-Structured as **vertical slices** - each slice is independently testable.
+结构化为**垂直切片** - 每个切片都是独立可测试的。
---
-### Slice 1: "What's Ready?" (Core Query) ✅ COMPLETE
+### 切片 1："什么准备好了？"（核心查询）✅ 完成
-**Delivers:** Types + Graph + State Detection + Schema Resolution
+**交付：** 类型 + 图 + 状态检测 + Schema 解析
-**Implementation:** `src/core/artifact-graph/`
-- `types.ts` - Zod schemas and derived TypeScript types
-- `schema.ts` - YAML parsing with Zod validation
-- `graph.ts` - ArtifactGraph class with topological sort
-- `state.ts` - Filesystem-based state detection
-- `resolver.ts` - XDG-compliant schema resolution
-- `builtin-schemas.ts` - Package-bundled default schemas
+**实施：** `src/core/artifact-graph/`
+- `types.ts` - Zod schema 和派生的 TypeScript 类型
+- `schema.ts` - 使用 Zod 验证的 YAML 解析
+- `graph.ts` - 具有拓扑排序的 ArtifactGraph 类
+- `state.ts` - 基于文件系统的状态检测
+- `resolver.ts` - XDG 兼容的 schema 解析
+- `builtin-schemas.ts` - 包捆绑的默认 schema
-**Key decisions made:**
-- Zod for schema validation (consistent with project)
-- XDG for global schema overrides
-- `Set` for completion state (immutable, functional)
-- `inProgress` and `failed` states deferred (require external tracking)
+**做出的关键决策：**
+- Zod 用于 schema 验证（与项目一致）
+- XDG 用于全局 schema 覆盖
+- `Set` 用于完成状态（不可变、函数式）
+- `inProgress` 和 `failed` 状态延迟（需要外部跟踪）
---
-### Slice 2: "Change Creation Utilities"
+### 切片 2："变更创建实用程序"
-**Delivers:** Utility functions for programmatic change creation
+**交付：** 用于程序化变更创建的实用函数
-**Scope:**
-- `createChange(projectRoot, name, description?)` → creates directory + README
-- `validateChangeName(name)` → kebab-case pattern enforcement
+**范围：**
+- `createChange(projectRoot, name, description?)` → 创建目录 + README
+- `validateChangeName(name)` → kebab-case 模式强制执行
-**Not in scope (already exists in CLI commands):**
-- `listChanges()` → exists in `ListCommand` and `ChangeCommand.getActiveChanges()`
-- `getChangePath()` → simple `path.join()` inline
-- `changeExists()` → simple `fs.access()` inline
-- `isInitialized()` → simple directory check inline
+**不在范围内（已存在于 CLI 命令中）：**
+- `listChanges()` → 存在于 `ListCommand` 和 `ChangeCommand.getActiveChanges()` 中
+- `getChangePath()` → 简单的内联 `path.join()`
+- `changeExists()` → 简单的内联 `fs.access()`
+- `isInitialized()` → 简单的内联目录检查
-**Why simplified:** Extracting existing CLI logic into a class would require similar refactoring of `SpecCommand` for consistency. The existing code works fine (~15 lines each). Only truly new functionality is `createChange()` + name validation.
+**为什么简化：** 将现有的 CLI 逻辑提取到类中需要类似地重构 `SpecCommand` 以保持一致性。现有代码工作正常（每个约 15 行）。唯一真正的新功能是 `createChange()` + 名称验证。
---
-### Slice 3: "Get Instructions" (Enrichment)
+### 切片 3："获取指令"（丰富）
-**Delivers:** Template resolution + context injection
+**交付：** 模板解析 + 上下文注入
-**Testable behaviors:**
-- Template fallback: schema-specific → shared → built-in → error
-- Context injection: completed deps show ✓, missing show ✗
-- Output path shown correctly based on change directory
+**可测试行为：**
+- 模板回退：特定于 schema → 共享 → 内置 → 错误
+- 上下文注入：已完成的依赖项显示 ✓，缺少的显示 ✗
+- 根据变更目录正确显示输出路径
---
-### Slice 4: "CLI + Integration"
+### 切片 4："CLI + 集成"
-**Delivers:** New artifact graph commands (builds on existing CLI)
+**交付：** 新的工件图命令（基于现有 CLI 构建）
-**New commands:**
-- `status --change ` - Show artifact completion state
-- `next --change ` - Show ready-to-create artifacts
-- `instructions --change ` - Get enriched template
-- `templates --change ` - Show resolved paths
-- `new ` - Create change (wrapper for `createChange()`)
+**新命令：**
+- `status --change ` - 显示工件完成状态
+- `next --change ` - 显示准备创建的工件
+- `instructions --change ` - 获取丰富的模板
+- `templates --change ` - 显示解析的路径
+- `new ` - 创建变更（`createChange()` 的包装器）
-**Already exists (not in scope):**
-- `openspec change list/show/validate` - change management
-- `openspec list --changes/--specs` - listing
-- `openspec view` - dashboard
-- `openspec init` - initialization
+**已存在（不在范围内）：**
+- `openspec change list/show/validate` - 变更管理
+- `openspec list --changes/--specs` - 列表
+- `openspec view` - 仪表板
+- `openspec init` - 初始化
-**Testable behaviors:**
-- Each new command produces expected output
-- Commands compose correctly (status → next → instructions flow)
-- Error handling for missing changes, invalid artifacts, etc.
+**可测试行为：**
+- 每个新命令产生预期的输出
+- 命令正确组合（status → next → instructions 流程）
+- 缺少变更、无效工件等的错误处理
---
-## Directory Structure
+## 目录结构
```
-# Global (XDG paths - user overrides)
+# 全局（XDG 路径 - 用户覆盖）
~/.local/share/openspec/ # Unix/macOS ($XDG_DATA_HOME/openspec/)
%LOCALAPPDATA%/openspec/ # Windows
-└── schemas/ # Schema overrides
- └── custom-workflow/ # User-defined schema directory
- ├── schema.yaml # Schema definition
- └── templates/ # Co-located templates
+└── schemas/ # Schema 覆盖
+ └── custom-workflow/ # 用户定义的 schema 目录
+ ├── schema.yaml # Schema 定义
+ └── templates/ # 共同位于的模板
└── proposal.md
-# Package (built-in defaults)
+# 包（内置默认值）
/
-└── schemas/ # Built-in schema definitions
- ├── spec-driven/ # Default: proposal → specs → design → tasks
+└── schemas/ # 内置 schema 定义
+ ├── spec-driven/ # 默认：proposal → specs → design → tasks
│ ├── schema.yaml
│ └── templates/
│ ├── proposal.md
│ ├── design.md
│ ├── spec.md
│ └── tasks.md
- └── tdd/ # TDD: tests → implementation → docs
+ └── tdd/ # TDD：tests → implementation → docs
├── schema.yaml
└── templates/
├── test.md
@@ -507,54 +509,54 @@ Structured as **vertical slices** - each slice is independently testable.
├── spec.md
└── docs.md
-# Project (change instances)
+# 项目（变更实例）
openspec/
-└── changes/ # Change instances
+└── changes/ # 变更实例
├── add-auth/
- │ ├── README.md # Auto-generated on creation
- │ ├── proposal.md # Created artifacts
+ │ ├── README.md # 创建时自动生成
+ │ ├── proposal.md # 创建的工件
│ ├── design.md
│ └── specs/
│ └── *.md
├── refactor-db/
│ └── ...
- └── archive/ # Completed changes
+ └── archive/ # 已完成的变更
└── 2025-01-01-add-auth/
.claude/
-├── settings.local.json # Permissions
-└── commands/ # Slash commands
+├── settings.local.json # 权限
+└── commands/ # 斜杠命令
└── *.md
```
---
-## Schema YAML Format
+## Schema YAML 格式
```yaml
-# Built-in: /schemas/spec-driven/schema.yaml
-# Or user override: ~/.local/share/openspec/schemas/spec-driven/schema.yaml
+# 内置：/schemas/spec-driven/schema.yaml
+# 或用户覆盖：~/.local/share/openspec/schemas/spec-driven/schema.yaml
name: spec-driven
version: 1
-description: Specification-driven development
+description: 规范驱动的开发
artifacts:
- id: proposal
generates: "proposal.md"
- description: "Create project proposal document"
- template: "proposal.md" # resolves from co-located templates/ directory
+ description: "创建项目提案文档"
+ template: "proposal.md" # 从共同位于的 templates/ 目录解析
requires: []
- id: specs
- generates: "specs/*.md" # glob pattern
- description: "Create technical specification documents"
+ generates: "specs/*.md" # glob 模式
+ description: "创建技术规范文档"
template: "specs.md"
requires:
- proposal
- id: design
generates: "design.md"
- description: "Create design document"
+ description: "创建设计文档"
template: "design.md"
requires:
- proposal
@@ -562,7 +564,7 @@ artifacts:
- id: tasks
generates: "tasks.md"
- description: "Create tasks breakdown document"
+ description: "创建任务分解文档"
template: "tasks.md"
requires:
- design
@@ -570,28 +572,28 @@ artifacts:
---
-## Summary
+## 摘要
-| Layer | Component | Responsibility | Status |
+| 层 | 组件 | 职责 | 状态 |
|-------|-----------|----------------|--------|
-| Core | ArtifactGraph | Pure dependency logic + XDG schema resolution | ✅ Slice 1 COMPLETE |
-| Utils | change-utils | Change creation + name validation only | Slice 2 (new functionality only) |
-| Core | InstructionLoader | Template resolution + enrichment | Slice 3 (all new) |
-| Presentation | CLI | New artifact graph commands | Slice 4 (new commands only) |
-| Integration | Claude Commands | AI assistant glue | Slice 4 |
-
-**What already exists (not in this proposal):**
-- `getActiveChangeIds()` in `src/utils/item-discovery.ts` - list changes
-- `ChangeCommand.list/show/validate()` in `src/commands/change.ts`
-- `ListCommand.execute()` in `src/core/list.ts`
-- `ViewCommand.execute()` in `src/core/view.ts` - dashboard
-- `src/core/init.ts` - initialization
-- `src/core/archive.ts` - archiving
-
-**Key Principles:**
-- **Filesystem IS the database** - stateless, version-control friendly
-- **Dependencies are enablers** - show what's possible, don't force order
-- **Deterministic CLI, inferring agent** - CLI requires explicit `--change`, agent infers from context
-- **XDG-compliant paths** - schemas and templates use standard user data directories
-- **2-level inheritance** - user override → package built-in (no deeper)
-- **Schemas are versioned** - support variations by philosophy, version, language
+| 核心 | ArtifactGraph | 纯依赖逻辑 + XDG schema 解析 | ✅ 切片 1 完成 |
+| 实用程序 | change-utils | 仅变更创建 + 名称验证 | 切片 2（仅新功能） |
+| 核心 | InstructionLoader | 模板解析 + 丰富 | 切片 3（全新） |
+| 表示 | CLI | 新的工件图命令 | 切片 4（仅新命令） |
+| 集成 | Claude Commands | AI 助手粘合剂 | 切片 4 |
+
+**已存在的内容（不在此提案中）：**
+- `src/utils/item-discovery.ts` 中的 `getActiveChangeIds()` - 列出变更
+- `src/commands/change.ts` 中的 `ChangeCommand.list/show/validate()`
+- `src/core/list.ts` 中的 `ListCommand.execute()`
+- `src/core/view.ts` 中的 `ViewCommand.execute()` - 仪表板
+- `src/core/init.ts` - 初始化
+- `src/core/archive.ts` - 归档
+
+**关键原则：**
+- **文件系统就是数据库** - 无状态、版本控制友好
+- **依赖关系是启用器** - 显示可能的内容，不强制顺序
+- **确定性 CLI，推断代理** - CLI 需要显式的 `--change`，代理从上下文推断
+- **XDG 兼容路径** - schema 和模板使用标准用户数据目录
+- **2 级继承** - 用户覆盖 → 包内置（不更深）
+- **Schema 是版本化的** - 支持按理念、版本、语言的变体
diff --git a/docs/artifact_poc.zh-CN.md b/docs/artifact_poc.zh-CN.md
new file mode 100644
index 00000000..f1eb240f
--- /dev/null
+++ b/docs/artifact_poc.zh-CN.md
@@ -0,0 +1,599 @@
+# POC-OpenSpec-Core 分析
+
+> [English Version](artifact_poc.md)
+
+---
+
+## 设计决策与术语
+
+### 理念：不是工作流系统
+
+该系统**不是**工作流引擎。它是一个**具有依赖关系感知的工件跟踪器**。
+
+| 它不是什么 | 它是什么 |
+|---------------|------------|
+| 线性的逐步进展 | 探索性的、迭代的规划 |
+| 官僚式的检查点 | 解锁可能性的启用器 |
+| "您必须先完成步骤 1" | "这是您现在可以创建的内容" |
+| 填表 | 流畅的文档创建 |
+
+**关键见解：** 依赖关系是*启用器*，而不是*门槛*。如果没有提案可供设计，您就无法有意义地编写设计文档 - 这不是官僚主义，这是逻辑。
+
+### 术语
+
+| 术语 | 定义 | 示例 |
+|------|------------|---------|
+| **Change** | 正在规划的工作单元（功能、重构、迁移） | `openspec/changes/add-auth/` |
+| **Schema** | 工件图定义（存在哪些工件，它们的依赖关系） | `spec-driven.yaml` |
+| **Artifact** | 图中的节点（要创建的文档） | `proposal`、`design`、`specs` |
+| **Template** | 创建工件的指令/指导 | `templates/proposal.md` |
+
+### 层次结构
+
+```
+Schema (定义) ──→ Artifacts (指导) ──→ Templates
+```
+
+- **Schema** = 工件图（存在什么，依赖关系）
+- **Artifact** = 要生成的文档
+- **Template** = 创建该工件的指令
+
+### Schema 变体
+
+Schema 可以在多个维度上变化：
+
+| 维度 | 示例 |
+|-----------|----------|
+| 理念 | `spec-driven`、`tdd`、`prototype-first` |
+| 版本 | `v1`、`v2`、`v3` |
+| 语言 | `en`、`zh`、`es` |
+| 自定义 | `team-alpha`、`experimental` |
+
+### Schema 解析（XDG 标准）
+
+Schema 遵循 XDG 基本目录规范，具有 2 级解析：
+
+```
+1. ${XDG_DATA_HOME}/openspec/schemas//schema.yaml # 全局用户覆盖
+2. /schemas//schema.yaml # 内置默认值
+```
+
+**特定平台路径：**
+- Unix/macOS：`~/.local/share/openspec/schemas/`
+- Windows：`%LOCALAPPDATA%/openspec/schemas/`
+- 所有平台：`$XDG_DATA_HOME/openspec/schemas/`（设置时）
+
+**为什么使用 XDG？**
+- Schema 是工作流定义（数据），而不是用户偏好（配置）
+- 内置的烘焙到包中，从不自动复制
+- 用户通过在全局数据目录中创建文件来自定义
+- 与现代 CLI 工具标准一致
+
+### 模板继承（最多 2 级）
+
+模板与 schema 共同位于 `templates/` 子目录中：
+
+```
+1. ${XDG_DATA_HOME}/openspec/schemas//templates/.md # 用户覆盖
+2. /schemas//templates/.md # 内置
+```
+
+**规则：**
+- 用户覆盖优先于包内置
+- CLI 命令显示解析的路径（无需猜测）
+- schema 之间没有继承（如果需要分歧，请复制）
+- 模板始终与其 schema 共同位于
+
+**为什么这很重要：**
+- 避免"这来自哪里？"的调试
+- 没有隐式魔法，直到它不起作用
+- Schema + 模板形成一个有凝聚力的单元
+
+---
+
+## 执行摘要
+
+这是一个**具有依赖关系感知的工件跟踪器**，通过结构化的工件管道指导迭代开发。核心创新是使用**文件系统作为数据库** - 工件完成由文件存在检测，使系统无状态且版本控制友好。
+
+系统回答：
+- "此变更存在哪些工件？"
+- "我接下来可以创建什么？"（不是"我必须创建什么"）
+- "什么阻止了 X？"（信息性的，而不是规定性的）
+
+---
+
+## 核心组件
+
+### 1. ArtifactGraph（切片 1 - 完成）
+
+具有 XDG 兼容 schema 解析的依赖图引擎。
+
+| 职责 | 方法 |
+|----------------|----------|
+| 将工件建模为 DAG | 具有 `requires: string[]` 的 Artifact |
+| 跟踪完成状态 | 已完成工件的 `Set` |
+| 计算构建顺序 | Kahn 算法（拓扑排序） |
+| 查找就绪工件 | 检查所有依赖项是否在 `completed` 集合中 |
+| 解析 schema | XDG 全局 → 包内置 |
+
+**关键数据结构（Zod 验证）：**
+
+```typescript
+// Zod schema 定义类型 + 验证
+const ArtifactSchema = z.object({
+ id: z.string().min(1),
+ generates: z.string().min(1), // 例如 "proposal.md" 或 "specs/*.md"
+ description: z.string(),
+ template: z.string(), // 模板文件路径
+ requires: z.array(z.string()).default([]),
+});
+
+const SchemaYamlSchema = z.object({
+ name: z.string().min(1),
+ version: z.number().int().positive(),
+ description: z.string().optional(),
+ artifacts: z.array(ArtifactSchema).min(1),
+});
+
+// 派生类型
+type Artifact = z.infer;
+type SchemaYaml = z.infer;
+```
+
+**关键方法：**
+- `resolveSchema(name)` - 使用 XDG 回退加载 schema
+- `ArtifactGraph.fromSchema(schema)` - 从 schema 构建图
+- `detectState(graph, changeDir)` - 扫描文件系统以完成
+- `getNextArtifacts(graph, completed)` - 查找准备创建的工件
+- `getBuildOrder(graph)` - 所有工件的拓扑排序
+- `getBlocked(graph, completed)` - 具有未满足依赖项的工件
+
+---
+
+### 2. Change 实用程序（切片 2）
+
+用于程序化变更创建的简单实用函数。没有类，没有抽象层。
+
+| 职责 | 方法 |
+|----------------|----------|
+| 创建变更 | 在 `openspec/changes//` 下创建目录并附带 README |
+| 名称验证 | 强制执行 kebab-case 命名 |
+
+**关键路径：**
+
+```
+openspec/changes// → 具有工件的变更实例（项目级别）
+```
+
+**关键函数**（`src/utils/change-utils.ts`）：
+- `createChange(projectRoot, name, description?)` - 创建新的变更目录 + README
+- `validateChangeName(name)` - 验证 kebab-case 命名，返回 `{ valid, error? }`
+
+**注意：** 现有的 CLI 命令（`ListCommand`、`ChangeCommand`）已经处理列表、路径解析和存在性检查。无需提取该逻辑 - 它按原样工作正常。
+
+---
+
+### 3. InstructionLoader（切片 3）
+
+模板解析和指令丰富。
+
+| 职责 | 方法 |
+|----------------|----------|
+| 解析模板 | XDG 2 级回退（特定于 schema → 共享 → 内置） |
+| 构建动态上下文 | 收集依赖状态、变更信息 |
+| 丰富模板 | 将上下文注入基础模板 |
+| 生成状态报告 | 带有进度的格式化 markdown |
+
+**关键类 - ChangeState：**
+
+```
+ChangeState {
+ changeName: string
+ changeDir: string
+ graph: ArtifactGraph
+ completed: Set
+
+ // 方法
+ getNextSteps(): string[]
+ getStatus(artifactId): ArtifactStatus
+ isComplete(): boolean
+}
+```
+
+**关键函数：**
+- `getTemplatePath(artifactId, schemaName?)` - 使用 2 级回退解析
+- `getEnrichedInstructions(artifactId, projectRoot, changeName?)` - 主入口点
+- `getChangeStatus(projectRoot, changeName?)` - 格式化状态报告
+
+---
+
+### 4. CLI（切片 4）
+
+用户界面层。**所有命令都是确定性的** - 需要显式的 `--change` 参数。
+
+| 命令 | 功能 | 状态 |
+|---------|----------|--------|
+| `status --change ` | 显示变更进度（工件图） | **新** |
+| `next --change ` | 显示准备创建的工件 | **新** |
+| `instructions --change ` | 获取工件的丰富指令 | **新** |
+| `list` | 列出所有变更 | 存在（`openspec change list`） |
+| `new ` | 创建变更 | **新**（使用 `createChange()`） |
+| `init` | 初始化结构 | 存在（`openspec init`） |
+| `templates --change ` | 显示解析的模板路径 | **新** |
+
+**注意：** 对变更进行操作的命令需要 `--change`。缺少参数 → 错误，并显示可用变更列表。代理从对话中推断变更并明确传递它。
+
+**现有的 CLI 命令**（不属于此切片）：
+- `openspec change list` / `openspec change show ` / `openspec change validate `
+- `openspec list --changes` / `openspec list --specs`
+- `openspec view`（仪表板）
+- `openspec init` / `openspec archive `
+
+---
+
+### 5. Claude 命令
+
+Claude Code 的集成层。**仅操作命令** - 通过自然语言创建工件。
+
+| 命令 | 目的 |
+|---------|---------|
+| `/status` | 显示变更进度 |
+| `/next` | 显示准备创建的内容 |
+| `/run [artifact]` | 执行特定步骤（高级用户） |
+| `/list` | 列出所有变更 |
+| `/new ` | 创建新变更 |
+| `/init` | 初始化结构 |
+
+**工件创建：** 用户用自然语言说"创建提案"或"编写测试"。代理：
+1. 从对话中推断变更（如果不确定则确认）
+2. 从请求中推断工件
+3. 使用显式的 `--change` 参数调用 CLI
+4. 按照指令创建工件
+
+这适用于任何 schema 中的任何工件 - 当 schema 更改时不需要新的斜杠命令。
+
+**注意：** 遗留命令（`/openspec-proposal`、`/openspec-apply`、`/openspec-archive`）存在于主项目中以实现向后兼容性，但与此架构分离。
+
+---
+
+## 组件依赖图
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 表示层 │
+│ ┌──────────────┐ ┌────────────────────┐ │
+│ │ CLI │ ←─shell exec───────│ Claude Commands │ │
+│ └──────┬───────┘ └────────────────────┘ │
+└─────────┼───────────────────────────────────────────────────┘
+ │ imports
+ ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 编排层 │
+│ ┌────────────────────┐ ┌──────────────────────────┐ │
+│ │ InstructionLoader │ │ change-utils (切片 2) │ │
+│ │ (切片 3) │ │ createChange() │ │
+│ └─────────┬──────────┘ │ validateChangeName() │ │
+│ │ └──────────────────────────┘ │
+└────────────┼────────────────────────────────────────────────┘
+ │ uses
+ ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 核心层 │
+│ ┌──────────────────────────────────────────────────────┐ │
+│ │ ArtifactGraph (切片 1) │ │
+│ │ │ │
+│ │ Schema 解析 (XDG) ──→ 图 ──→ 状态检测 │ │
+│ └──────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+ ▲
+ │ reads from
+ ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 持久层 │
+│ ┌──────────────────┐ ┌────────────────────────────────┐ │
+│ │ XDG Schemas │ │ 项目工件 │ │
+│ │ ~/.local/share/ │ │ openspec/changes// │ │
+│ │ openspec/ │ │ - proposal.md, design.md │ │
+│ │ schemas/ │ │ - specs/*.md, tasks.md │ │
+│ └──────────────────┘ └────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 关键设计模式
+
+### 1. 文件系统作为数据库
+
+没有 SQLite，没有 JSON 状态文件。`proposal.md` 的存在意味着提案已完成。
+
+```
+// 状态检测只是文件存在性检查
+if (exists(artifactPath)) {
+ completed.add(artifactId)
+}
+```
+
+### 2. 确定性 CLI，推断代理
+
+**CLI 层：** 始终确定性 - 需要显式的 `--change` 参数。
+
+```
+openspec status --change add-auth # 显式，有效
+openspec status # 错误："未指定变更"
+```
+
+**代理层：** 从对话中推断，如果不确定则确认，传递显式的 `--change`。
+
+这种分离意味着：
+- CLI 是纯粹的、可测试的，没有要损坏的状态
+- 代理处理所有"智能"
+- 没有跟踪"活跃变更"的 config.yaml
+
+### 3. XDG 兼容的 Schema 解析
+
+```
+${XDG_DATA_HOME}/openspec/schemas//schema.yaml # 用户覆盖
+ ↓ (未找到)
+/schemas//schema.yaml # 内置
+ ↓ (未找到)
+错误（未找到 schema）
+```
+
+### 4. 两级模板回退
+
+```
+${XDG_DATA_HOME}/openspec/schemas//templates/.md # 用户覆盖
+ ↓ (未找到)
+/schemas//templates/.md # 内置
+ ↓ (未找到)
+错误（没有静默回退以避免混淆）
+```
+
+### 5. Glob 模式支持
+
+`specs/*.md` 允许多个文件满足单个工件：
+
+```
+if (artifact.generates.includes("*")) {
+ const parentDir = changeDir / patternParts[0]
+ if (exists(parentDir) && hasFiles(parentDir)) {
+ completed.add(artifactId)
+ }
+}
+```
+
+### 6. 无状态状态检测
+
+每个命令都重新扫描文件系统。没有要损坏的缓存状态。
+
+---
+
+## 工件管道（默认 Schema）
+
+默认的 `spec-driven` schema：
+
+```
+┌──────────┐
+│ proposal │ (无依赖)
+└────┬─────┘
+ │
+ ▼
+┌──────────┐
+│ specs │ (requires: proposal)
+└────┬─────┘
+ │
+ ├──────────────┐
+ ▼ ▼
+┌──────────┐ ┌──────────┐
+│ design │ │ │
+│ │◄──┤ proposal │
+└────┬─────┘ └──────────┘
+ │ (requires: proposal, specs)
+ ▼
+┌──────────┐
+│ tasks │ (requires: design)
+└──────────┘
+```
+
+其他 schema（TDD、prototype-first）将具有不同的图。
+
+---
+
+## 实施顺序
+
+结构化为**垂直切片** - 每个切片都是独立可测试的。
+
+---
+
+### 切片 1："什么准备好了？"（核心查询）✅ 完成
+
+**交付：** 类型 + 图 + 状态检测 + Schema 解析
+
+**实施：** `src/core/artifact-graph/`
+- `types.ts` - Zod schema 和派生的 TypeScript 类型
+- `schema.ts` - 使用 Zod 验证的 YAML 解析
+- `graph.ts` - 具有拓扑排序的 ArtifactGraph 类
+- `state.ts` - 基于文件系统的状态检测
+- `resolver.ts` - XDG 兼容的 schema 解析
+- `builtin-schemas.ts` - 包捆绑的默认 schema
+
+**做出的关键决策：**
+- Zod 用于 schema 验证（与项目一致）
+- XDG 用于全局 schema 覆盖
+- `Set` 用于完成状态（不可变、函数式）
+- `inProgress` 和 `failed` 状态延迟（需要外部跟踪）
+
+---
+
+### 切片 2："变更创建实用程序"
+
+**交付：** 用于程序化变更创建的实用函数
+
+**范围：**
+- `createChange(projectRoot, name, description?)` → 创建目录 + README
+- `validateChangeName(name)` → kebab-case 模式强制执行
+
+**不在范围内（已存在于 CLI 命令中）：**
+- `listChanges()` → 存在于 `ListCommand` 和 `ChangeCommand.getActiveChanges()` 中
+- `getChangePath()` → 简单的内联 `path.join()`
+- `changeExists()` → 简单的内联 `fs.access()`
+- `isInitialized()` → 简单的内联目录检查
+
+**为什么简化：** 将现有的 CLI 逻辑提取到类中需要类似地重构 `SpecCommand` 以保持一致性。现有代码工作正常（每个约 15 行）。唯一真正的新功能是 `createChange()` + 名称验证。
+
+---
+
+### 切片 3："获取指令"（丰富）
+
+**交付：** 模板解析 + 上下文注入
+
+**可测试行为：**
+- 模板回退：特定于 schema → 共享 → 内置 → 错误
+- 上下文注入：已完成的依赖项显示 ✓，缺少的显示 ✗
+- 根据变更目录正确显示输出路径
+
+---
+
+### 切片 4："CLI + 集成"
+
+**交付：** 新的工件图命令（基于现有 CLI 构建）
+
+**新命令：**
+- `status --change ` - 显示工件完成状态
+- `next --change ` - 显示准备创建的工件
+- `instructions --change ` - 获取丰富的模板
+- `templates --change ` - 显示解析的路径
+- `new ` - 创建变更（`createChange()` 的包装器）
+
+**已存在（不在范围内）：**
+- `openspec change list/show/validate` - 变更管理
+- `openspec list --changes/--specs` - 列表
+- `openspec view` - 仪表板
+- `openspec init` - 初始化
+
+**可测试行为：**
+- 每个新命令产生预期的输出
+- 命令正确组合（status → next → instructions 流程）
+- 缺少变更、无效工件等的错误处理
+
+---
+
+## 目录结构
+
+```
+# 全局（XDG 路径 - 用户覆盖）
+~/.local/share/openspec/ # Unix/macOS ($XDG_DATA_HOME/openspec/)
+%LOCALAPPDATA%/openspec/ # Windows
+└── schemas/ # Schema 覆盖
+ └── custom-workflow/ # 用户定义的 schema 目录
+ ├── schema.yaml # Schema 定义
+ └── templates/ # 共同位于的模板
+ └── proposal.md
+
+# 包（内置默认值）
+/
+└── schemas/ # 内置 schema 定义
+ ├── spec-driven/ # 默认：proposal → specs → design → tasks
+ │ ├── schema.yaml
+ │ └── templates/
+ │ ├── proposal.md
+ │ ├── design.md
+ │ ├── spec.md
+ │ └── tasks.md
+ └── tdd/ # TDD：tests → implementation → docs
+ ├── schema.yaml
+ └── templates/
+ ├── test.md
+ ├── implementation.md
+ ├── spec.md
+ └── docs.md
+
+# 项目（变更实例）
+openspec/
+└── changes/ # 变更实例
+ ├── add-auth/
+ │ ├── README.md # 创建时自动生成
+ │ ├── proposal.md # 创建的工件
+ │ ├── design.md
+ │ └── specs/
+ │ └── *.md
+ ├── refactor-db/
+ │ └── ...
+ └── archive/ # 已完成的变更
+ └── 2025-01-01-add-auth/
+
+.claude/
+├── settings.local.json # 权限
+└── commands/ # 斜杠命令
+ └── *.md
+```
+
+---
+
+## Schema YAML 格式
+
+```yaml
+# 内置：/schemas/spec-driven/schema.yaml
+# 或用户覆盖：~/.local/share/openspec/schemas/spec-driven/schema.yaml
+name: spec-driven
+version: 1
+description: 规范驱动的开发
+
+artifacts:
+ - id: proposal
+ generates: "proposal.md"
+ description: "创建项目提案文档"
+ template: "proposal.md" # 从共同位于的 templates/ 目录解析
+ requires: []
+
+ - id: specs
+ generates: "specs/*.md" # glob 模式
+ description: "创建技术规范文档"
+ template: "specs.md"
+ requires:
+ - proposal
+
+ - id: design
+ generates: "design.md"
+ description: "创建设计文档"
+ template: "design.md"
+ requires:
+ - proposal
+ - specs
+
+ - id: tasks
+ generates: "tasks.md"
+ description: "创建任务分解文档"
+ template: "tasks.md"
+ requires:
+ - design
+```
+
+---
+
+## 摘要
+
+| 层 | 组件 | 职责 | 状态 |
+|-------|-----------|----------------|--------|
+| 核心 | ArtifactGraph | 纯依赖逻辑 + XDG schema 解析 | ✅ 切片 1 完成 |
+| 实用程序 | change-utils | 仅变更创建 + 名称验证 | 切片 2（仅新功能） |
+| 核心 | InstructionLoader | 模板解析 + 丰富 | 切片 3（全新） |
+| 表示 | CLI | 新的工件图命令 | 切片 4（仅新命令） |
+| 集成 | Claude Commands | AI 助手粘合剂 | 切片 4 |
+
+**已存在的内容（不在此提案中）：**
+- `src/utils/item-discovery.ts` 中的 `getActiveChangeIds()` - 列出变更
+- `src/commands/change.ts` 中的 `ChangeCommand.list/show/validate()`
+- `src/core/list.ts` 中的 `ListCommand.execute()`
+- `src/core/view.ts` 中的 `ViewCommand.execute()` - 仪表板
+- `src/core/init.ts` - 初始化
+- `src/core/archive.ts` - 归档
+
+**关键原则：**
+- **文件系统就是数据库** - 无状态、版本控制友好
+- **依赖关系是启用器** - 显示可能的内容，不强制顺序
+- **确定性 CLI，推断代理** - CLI 需要显式的 `--change`，代理从上下文推断
+- **XDG 兼容路径** - schema 和模板使用标准用户数据目录
+- **2 级继承** - 用户覆盖 → 包内置（不更深）
+- **Schema 是版本化的** - 支持按理念、版本、语言的变体
diff --git a/docs/schema-customization.md b/docs/schema-customization.md
index d4cc3f25..c236e10e 100644
--- a/docs/schema-customization.md
+++ b/docs/schema-customization.md
@@ -1,172 +1,174 @@
-# Schema Customization
+# Schema 自定义
-This document describes how users can customize OpenSpec schemas and templates, the current manual process, and the gap that needs to be addressed.
+本文档描述了用户如何自定义 OpenSpec schema 和模板、当前的手动流程以及需要解决的差距。
+
+> [English Version](schema-customization.md)
---
-## Overview
+## 概述
-OpenSpec uses a 2-level schema resolution system following the XDG Base Directory Specification:
+OpenSpec 使用遵循 XDG 基本目录规范的 2 级 schema 解析系统：
-1. **User override**: `${XDG_DATA_HOME}/openspec/schemas//`
-2. **Package built-in**: `/schemas//`
+1. **用户覆盖**：`${XDG_DATA_HOME}/openspec/schemas//`
+2. **包内置**：`/schemas//`
-When a schema is requested (e.g., `spec-driven`), the resolver checks the user directory first. If found, that entire schema directory is used. Otherwise, it falls back to the package's built-in schema.
+当请求 schema（例如 `spec-driven`）时，解析器首先检查用户目录。如果找到，则使用整个 schema 目录。否则，它会回退到包的内置 schema。
---
-## Current Manual Process
+## 当前的手动流程
-To override the default `spec-driven` schema, a user must:
+要覆盖默认的 `spec-driven` schema，用户必须：
-### 1. Determine the correct directory path
+### 1. 确定正确的目录路径
-| Platform | Path |
+| 平台 | 路径 |
|----------|------|
| macOS/Linux | `~/.local/share/openspec/schemas/` |
| Windows | `%LOCALAPPDATA%\openspec\schemas\` |
-| All (if set) | `$XDG_DATA_HOME/openspec/schemas/` |
+| 所有（如果设置） | `$XDG_DATA_HOME/openspec/schemas/` |
-### 2. Create the directory structure
+### 2. 创建目录结构
```bash
-# macOS/Linux example
+# macOS/Linux 示例
mkdir -p ~/.local/share/openspec/schemas/spec-driven/templates
```
-### 3. Find and copy the default schema files
+### 3. 查找并复制默认 schema 文件
-The user must locate the installed npm package to copy the defaults:
+用户必须找到已安装的 npm 包以复制默认值：
```bash
-# Find the package location (varies by install method)
+# 查找包位置（因安装方法而异）
npm list -g openspec --parseable
-# or
+# 或
which openspec && readlink -f $(which openspec)
-# Copy files from the package's schemas/ directory
+# 从包的 schemas/ 目录复制文件
cp /schemas/spec-driven/schema.yaml ~/.local/share/openspec/schemas/spec-driven/
cp /schemas/spec-driven/templates/*.md ~/.local/share/openspec/schemas/spec-driven/templates/
```
-### 4. Modify the copied files
+### 4. 修改复制的文件
-Edit `schema.yaml` to change the workflow structure:
+编辑 `schema.yaml` 以更改工作流结构：
```yaml
name: spec-driven
version: 1
-description: My custom workflow
+description: 我的自定义工作流
artifacts:
- id: proposal
generates: proposal.md
- description: Initial proposal
+ description: 初始提案
template: proposal.md
requires: []
- # Add, remove, or modify artifacts...
+ # 添加、删除或修改工件...
```
-Edit templates in `templates/` to customize the content guidance.
+编辑 `templates/` 中的模板以自定义内容指导。
-### 5. Verify the override is active
+### 5. 验证覆盖是否处于活动状态
-Currently there's no command to verify which schema is being used. Users must trust that the file exists in the right location.
+目前没有命令来验证正在使用哪个 schema。用户必须相信文件存在于正确的位置。
---
-## Gap Analysis
+## 差距分析
-The current process has several friction points:
+当前流程有几个摩擦点：
-| Issue | Impact |
+| 问题 | 影响 |
|-------|--------|
-| **Path discovery** | Users must know XDG conventions and platform-specific paths |
-| **Package location** | Finding the npm package path varies by install method (global, local, pnpm, yarn, volta, etc.) |
-| **No scaffolding** | Users must manually create directories and copy files |
-| **No verification** | No way to confirm which schema is actually being resolved |
-| **No diffing** | When upgrading openspec, users can't see what changed in built-in templates |
-| **Full copy required** | Must copy entire schema even to change one template |
+| **路径发现** | 用户必须了解 XDG 约定和特定于平台的路径 |
+| **包位置** | 查找 npm 包路径因安装方法而异（全局、本地、pnpm、yarn、volta 等） |
+| **没有脚手架** | 用户必须手动创建目录和复制文件 |
+| **没有验证** | 无法确认实际解析的是哪个 schema |
+| **没有差异比较** | 升级 openspec 时，用户无法看到内置模板中的更改 |
+| **需要完整复制** | 即使只更改一个模板，也必须复制整个 schema |
-### User Stories Not Currently Supported
+### 当前不支持的用户故事
-1. *"I want to add a `research` artifact before `proposal`"* — requires manual copy and edit
-2. *"I want to customize just the proposal template"* — must copy entire schema
-3. *"I want to see what the default schema looks like"* — must find package path
-4. *"I want to revert to defaults"* — must delete files and hope paths are correct
-5. *"I upgraded openspec, did the templates change?"* — no way to diff
+1. *"我想在 `proposal` 之前添加一个 `research` 工件"* — 需要手动复制和编辑
+2. *"我只想自定义提案模板"* — 必须复制整个 schema
+3. *"我想看看默认 schema 是什么样子"* — 必须找到包路径
+4. *"我想恢复到默认值"* — 必须删除文件并希望路径正确
+5. *"我升级了 openspec，模板有变化吗？"* — 无法比较差异
---
-## Proposed Solution: Schema Configurator
+## 提议的解决方案：Schema 配置器
-A CLI command (or set of commands) that handles path resolution and file operations for users.
+一个 CLI 命令（或一组命令），为用户处理路径解析和文件操作。
-### Option A: Single `openspec schema` command
+### 选项 A：单个 `openspec schema` 命令
```bash
-# List available schemas (built-in and user overrides)
+# 列出可用的 schema（内置和用户覆盖）
openspec schema list
-# Show where a schema resolves from
+# 显示 schema 从哪里解析
openspec schema which spec-driven
-# Output: /Users/me/.local/share/openspec/schemas/spec-driven/ (user override)
-# Output: /usr/local/lib/node_modules/openspec/schemas/spec-driven/ (built-in)
+# 输出：/Users/me/.local/share/openspec/schemas/spec-driven/ (用户覆盖)
+# 输出：/usr/local/lib/node_modules/openspec/schemas/spec-driven/ (内置)
-# Copy a built-in schema to user directory for customization
+# 将内置 schema 复制到用户目录以进行自定义
openspec schema copy spec-driven
-# Creates ~/.local/share/openspec/schemas/spec-driven/ with all files
+# 创建 ~/.local/share/openspec/schemas/spec-driven/ 及所有文件
-# Show diff between user override and built-in
+# 显示用户覆盖和内置之间的差异
openspec schema diff spec-driven
-# Remove user override (revert to built-in)
+# 删除用户覆盖（恢复到内置）
openspec schema reset spec-driven
-# Validate a schema
+# 验证 schema
openspec schema validate spec-driven
```
-### Option B: Dedicated `openspec customize` command
+### 选项 B：专用的 `openspec customize` 命令
```bash
-# Interactive schema customization
+# 交互式 schema 自定义
openspec customize
-# Prompts: Which schema? What do you want to change? etc.
+# 提示：哪个 schema？您想更改什么？等等。
-# Copy and open for editing
+# 复制并打开以进行编辑
openspec customize spec-driven
-# Copies to user dir, prints path, optionally opens in $EDITOR
+# 复制到用户目录，打印路径，可选择在 $EDITOR 中打开
```
-### Option C: Init-time schema selection
+### 选项 C：初始化时的 schema 选择
```bash
-# During project init, offer schema customization
+# 在项目初始化期间，提供 schema 自定义
openspec init
-# ? Select a workflow schema:
-# > spec-driven (default)
+# ? 选择工作流 schema：
+# > spec-driven (默认)
# tdd
# minimal
-# custom (copy and edit)
+# custom (复制并编辑)
```
-### Recommended Approach
+### 推荐方法
-**Option A** provides the most flexibility and follows Unix conventions (subcommands for discrete operations). Key commands in priority order:
+**选项 A** 提供了最大的灵活性并遵循 Unix 约定（用于离散操作的子命令）。按优先级顺序的关键命令：
-1. `openspec schema list` — see what's available
-2. `openspec schema which ` — debug resolution
-3. `openspec schema copy ` — scaffold customization
-4. `openspec schema diff ` — compare with built-in
-5. `openspec schema reset ` — revert to defaults
+1. `openspec schema list` — 查看可用内容
+2. `openspec schema which ` — 调试解析
+3. `openspec schema copy ` — 脚手架自定义
+4. `openspec schema diff ` — 与内置比较
+5. `openspec schema reset ` — 恢复到默认值
---
-## Implementation Considerations
+## 实施考虑
-### Path Resolution
+### 路径解析
-The resolver already exists in `src/core/artifact-graph/resolver.ts`:
+解析器已存在于 `src/core/artifact-graph/resolver.ts` 中：
```typescript
export function getPackageSchemasDir(): string { ... }
@@ -175,37 +177,37 @@ export function getSchemaDir(name: string): string | null { ... }
export function listSchemas(): string[] { ... }
```
-New commands would leverage these existing functions.
+新命令将利用这些现有函数。
-### File Operations
+### 文件操作
-- Copy should preserve file permissions
-- Copy should not overwrite existing user files without `--force`
-- Reset should prompt for confirmation
+- 复制应保留文件权限
+- 复制不应在没有 `--force` 的情况下覆盖现有用户文件
+- 重置应提示确认
-### Template-Only Overrides
+### 仅模板覆盖
-A future enhancement could support overriding individual templates without copying the entire schema. This would require changes to the resolution logic:
+未来的增强功能可以支持覆盖单个模板而无需复制整个 schema。这需要更改解析逻辑：
```
-Current: schema dir (user) OR schema dir (built-in)
-Future: schema.yaml from user OR built-in
- + each template from user OR built-in (independent fallback)
+当前：schema 目录（用户）或 schema 目录（内置）
+未来：来自用户或内置的 schema.yaml
+ + 来自用户或内置的每个模板（独立回退）
```
-This adds complexity but enables the "I just want to change one template" use case.
+这增加了复杂性，但启用了"我只想更改一个模板"的用例。
---
-## Related Documents
+## 相关文档
-- [Schema Workflow Gaps](./schema-workflow-gaps.md) — End-to-end workflow analysis and phased implementation plan
+- [Schema 工作流差距](./schema-workflow-gaps.zh-CN.md) — 端到端工作流分析和分阶段实施计划
-## Related Files
+## 相关文件
-| File | Purpose |
+| 文件 | 目的 |
|------|---------|
-| `src/core/artifact-graph/resolver.ts` | Schema resolution logic |
-| `src/core/artifact-graph/instruction-loader.ts` | Template loading |
-| `src/core/global-config.ts` | XDG path helpers |
-| `schemas/spec-driven/` | Default schema and templates |
+| `src/core/artifact-graph/resolver.ts` | Schema 解析逻辑 |
+| `src/core/artifact-graph/instruction-loader.ts` | 模板加载 |
+| `src/core/global-config.ts` | XDG 路径助手 |
+| `schemas/spec-driven/` | 默认 schema 和模板 |
diff --git a/docs/schema-customization.zh-CN.md b/docs/schema-customization.zh-CN.md
new file mode 100644
index 00000000..c236e10e
--- /dev/null
+++ b/docs/schema-customization.zh-CN.md
@@ -0,0 +1,213 @@
+# Schema 自定义
+
+本文档描述了用户如何自定义 OpenSpec schema 和模板、当前的手动流程以及需要解决的差距。
+
+> [English Version](schema-customization.md)
+
+---
+
+## 概述
+
+OpenSpec 使用遵循 XDG 基本目录规范的 2 级 schema 解析系统：
+
+1. **用户覆盖**：`${XDG_DATA_HOME}/openspec/schemas//`
+2. **包内置**：`/schemas//`
+
+当请求 schema（例如 `spec-driven`）时，解析器首先检查用户目录。如果找到，则使用整个 schema 目录。否则，它会回退到包的内置 schema。
+
+---
+
+## 当前的手动流程
+
+要覆盖默认的 `spec-driven` schema，用户必须：
+
+### 1. 确定正确的目录路径
+
+| 平台 | 路径 |
+|----------|------|
+| macOS/Linux | `~/.local/share/openspec/schemas/` |
+| Windows | `%LOCALAPPDATA%\openspec\schemas\` |
+| 所有（如果设置） | `$XDG_DATA_HOME/openspec/schemas/` |
+
+### 2. 创建目录结构
+
+```bash
+# macOS/Linux 示例
+mkdir -p ~/.local/share/openspec/schemas/spec-driven/templates
+```
+
+### 3. 查找并复制默认 schema 文件
+
+用户必须找到已安装的 npm 包以复制默认值：
+
+```bash
+# 查找包位置（因安装方法而异）
+npm list -g openspec --parseable
+# 或
+which openspec && readlink -f $(which openspec)
+
+# 从包的 schemas/ 目录复制文件
+cp /schemas/spec-driven/schema.yaml ~/.local/share/openspec/schemas/spec-driven/
+cp /schemas/spec-driven/templates/*.md ~/.local/share/openspec/schemas/spec-driven/templates/
+```
+
+### 4. 修改复制的文件
+
+编辑 `schema.yaml` 以更改工作流结构：
+
+```yaml
+name: spec-driven
+version: 1
+description: 我的自定义工作流
+artifacts:
+ - id: proposal
+ generates: proposal.md
+ description: 初始提案
+ template: proposal.md
+ requires: []
+ # 添加、删除或修改工件...
+```
+
+编辑 `templates/` 中的模板以自定义内容指导。
+
+### 5. 验证覆盖是否处于活动状态
+
+目前没有命令来验证正在使用哪个 schema。用户必须相信文件存在于正确的位置。
+
+---
+
+## 差距分析
+
+当前流程有几个摩擦点：
+
+| 问题 | 影响 |
+|-------|--------|
+| **路径发现** | 用户必须了解 XDG 约定和特定于平台的路径 |
+| **包位置** | 查找 npm 包路径因安装方法而异（全局、本地、pnpm、yarn、volta 等） |
+| **没有脚手架** | 用户必须手动创建目录和复制文件 |
+| **没有验证** | 无法确认实际解析的是哪个 schema |
+| **没有差异比较** | 升级 openspec 时，用户无法看到内置模板中的更改 |
+| **需要完整复制** | 即使只更改一个模板，也必须复制整个 schema |
+
+### 当前不支持的用户故事
+
+1. *"我想在 `proposal` 之前添加一个 `research` 工件"* — 需要手动复制和编辑
+2. *"我只想自定义提案模板"* — 必须复制整个 schema
+3. *"我想看看默认 schema 是什么样子"* — 必须找到包路径
+4. *"我想恢复到默认值"* — 必须删除文件并希望路径正确
+5. *"我升级了 openspec，模板有变化吗？"* — 无法比较差异
+
+---
+
+## 提议的解决方案：Schema 配置器
+
+一个 CLI 命令（或一组命令），为用户处理路径解析和文件操作。
+
+### 选项 A：单个 `openspec schema` 命令
+
+```bash
+# 列出可用的 schema（内置和用户覆盖）
+openspec schema list
+
+# 显示 schema 从哪里解析
+openspec schema which spec-driven
+# 输出：/Users/me/.local/share/openspec/schemas/spec-driven/ (用户覆盖)
+# 输出：/usr/local/lib/node_modules/openspec/schemas/spec-driven/ (内置)
+
+# 将内置 schema 复制到用户目录以进行自定义
+openspec schema copy spec-driven
+# 创建 ~/.local/share/openspec/schemas/spec-driven/ 及所有文件
+
+# 显示用户覆盖和内置之间的差异
+openspec schema diff spec-driven
+
+# 删除用户覆盖（恢复到内置）
+openspec schema reset spec-driven
+
+# 验证 schema
+openspec schema validate spec-driven
+```
+
+### 选项 B：专用的 `openspec customize` 命令
+
+```bash
+# 交互式 schema 自定义
+openspec customize
+# 提示：哪个 schema？您想更改什么？等等。
+
+# 复制并打开以进行编辑
+openspec customize spec-driven
+# 复制到用户目录，打印路径，可选择在 $EDITOR 中打开
+```
+
+### 选项 C：初始化时的 schema 选择
+
+```bash
+# 在项目初始化期间，提供 schema 自定义
+openspec init
+# ? 选择工作流 schema：
+# > spec-driven (默认)
+# tdd
+# minimal
+# custom (复制并编辑)
+```
+
+### 推荐方法
+
+**选项 A** 提供了最大的灵活性并遵循 Unix 约定（用于离散操作的子命令）。按优先级顺序的关键命令：
+
+1. `openspec schema list` — 查看可用内容
+2. `openspec schema which ` — 调试解析
+3. `openspec schema copy ` — 脚手架自定义
+4. `openspec schema diff ` — 与内置比较
+5. `openspec schema reset ` — 恢复到默认值
+
+---
+
+## 实施考虑
+
+### 路径解析
+
+解析器已存在于 `src/core/artifact-graph/resolver.ts` 中：
+
+```typescript
+export function getPackageSchemasDir(): string { ... }
+export function getUserSchemasDir(): string { ... }
+export function getSchemaDir(name: string): string | null { ... }
+export function listSchemas(): string[] { ... }
+```
+
+新命令将利用这些现有函数。
+
+### 文件操作
+
+- 复制应保留文件权限
+- 复制不应在没有 `--force` 的情况下覆盖现有用户文件
+- 重置应提示确认
+
+### 仅模板覆盖
+
+未来的增强功能可以支持覆盖单个模板而无需复制整个 schema。这需要更改解析逻辑：
+
+```
+当前：schema 目录（用户）或 schema 目录（内置）
+未来：来自用户或内置的 schema.yaml
+ + 来自用户或内置的每个模板（独立回退）
+```
+
+这增加了复杂性，但启用了"我只想更改一个模板"的用例。
+
+---
+
+## 相关文档
+
+- [Schema 工作流差距](./schema-workflow-gaps.zh-CN.md) — 端到端工作流分析和分阶段实施计划
+
+## 相关文件
+
+| 文件 | 目的 |
+|------|---------|
+| `src/core/artifact-graph/resolver.ts` | Schema 解析逻辑 |
+| `src/core/artifact-graph/instruction-loader.ts` | 模板加载 |
+| `src/core/global-config.ts` | XDG 路径助手 |
+| `schemas/spec-driven/` | 默认 schema 和模板 |
diff --git a/docs/schema-workflow-gaps.md b/docs/schema-workflow-gaps.md
index c378bc1e..48754dcc 100644
--- a/docs/schema-workflow-gaps.md
+++ b/docs/schema-workflow-gaps.md
@@ -1,137 +1,139 @@
-# Schema Workflow: End-to-End Analysis
+# Schema 工作流：端到端分析
-This document analyzes the complete user journey for working with schemas in OpenSpec, identifies gaps, and proposes a phased solution.
+本文档分析了在 OpenSpec 中使用 schema 的完整用户旅程，识别差距，并提出分阶段的解决方案。
+
+> [English Version](schema-workflow-gaps.md)
---
-## Current State
+## 当前状态
-### What Exists
+### 已存在的内容
-| Component | Status |
+| 组件 | 状态 |
|-----------|--------|
-| Schema resolution (XDG) | 2-level: user override → package built-in |
-| Built-in schemas | `spec-driven`, `tdd` |
-| Artifact workflow commands | `status`, `next`, `instructions`, `templates` with `--schema` flag |
-| Change creation | `openspec new change ` — no schema binding |
+| Schema 解析（XDG） | 2 级：用户覆盖 → 包内置 |
+| 内置 schema | `spec-driven`、`tdd` |
+| 工件工作流命令 | 带有 `--schema` 标志的 `status`、`next`、`instructions`、`templates` |
+| 变更创建 | `openspec new change ` — 没有 schema 绑定 |
-### What's Missing
+### 缺少的内容
-| Component | Status |
+| 组件 | 状态 |
|-----------|--------|
-| Schema bound to change | Not stored — must pass `--schema` every time |
-| Project-local schemas | Not supported — can't version control with repo |
-| Schema management CLI | None — manual path discovery required |
-| Project default schema | None — hardcoded to `spec-driven` |
+| 绑定到变更的 Schema | 未存储 — 每次都必须传递 `--schema` |
+| 项目本地 schema | 不支持 — 无法使用仓库进行版本控制 |
+| Schema 管理 CLI | 无 — 需要手动路径发现 |
+| 项目默认 schema | 无 — 硬编码为 `spec-driven` |
---
-## User Journey Analysis
+## 用户旅程分析
-### Scenario 1: Using a Non-Default Schema
+### 场景 1：使用非默认 Schema
-**Goal:** User wants to use TDD workflow for a new feature.
+**目标：** 用户想为新功能使用 TDD 工作流。
-**Today's experience:**
+**今天的体验：**
```bash
openspec new change add-auth
-# Creates directory, no schema info stored
+# 创建目录，未存储 schema 信息
openspec status --change add-auth
-# Shows spec-driven artifacts (WRONG - user wanted TDD)
+# 显示 spec-driven 工件（错误 - 用户想要 TDD）
-# User realizes mistake...
+# 用户意识到错误...
openspec status --change add-auth --schema tdd
-# Correct, but must remember --schema every time
+# 正确，但每次都必须记住 --schema
-# 6 months later...
+# 6 个月后...
openspec status --change add-auth
-# Wrong again - nobody remembers this was TDD
+# 又错了 - 没人记得这是 TDD
```
-**Problems:**
-- Schema is a runtime argument, not persisted
-- Easy to forget `--schema` and get wrong results
-- No record of intended schema for future reference
+**问题：**
+- Schema 是运行时参数，未持久化
+- 容易忘记 `--schema` 并得到错误的结果
+- 没有记录预期的 schema 以供将来参考
---
-### Scenario 2: Customizing a Schema
+### 场景 2：自定义 Schema
-**Goal:** User wants to add a "research" artifact before "proposal".
+**目标：** 用户想在"proposal"之前添加"research"工件。
-**Today's experience:**
+**今天的体验：**
```bash
-# Step 1: Figure out where to put overrides
-# Must know XDG conventions:
-# macOS/Linux: ~/.local/share/openspec/schemas/
-# Windows: %LOCALAPPDATA%\openspec\schemas/
+# 步骤 1：弄清楚在哪里放置覆盖
+# 必须了解 XDG 约定：
+# macOS/Linux：~/.local/share/openspec/schemas/
+# Windows：%LOCALAPPDATA%\openspec\schemas/
-# Step 2: Create directory structure
+# 步骤 2：创建目录结构
mkdir -p ~/.local/share/openspec/schemas/my-workflow/templates
-# Step 3: Find the npm package to copy defaults
+# 步骤 3：找到 npm 包以复制默认值
npm list -g openspec --parseable
-# Output varies by package manager:
-# npm: /usr/local/lib/node_modules/openspec
-# pnpm: ~/.local/share/pnpm/global/5/node_modules/openspec
-# volta: ~/.volta/tools/image/packages/openspec/...
-# yarn: ~/.config/yarn/global/node_modules/openspec
+# 输出因包管理器而异：
+# npm：/usr/local/lib/node_modules/openspec
+# pnpm：~/.local/share/pnpm/global/5/node_modules/openspec
+# volta：~/.volta/tools/image/packages/openspec/...
+# yarn：~/.config/yarn/global/node_modules/openspec
-# Step 4: Copy files
+# 步骤 4：复制文件
cp -r /schemas/spec-driven/* \
~/.local/share/openspec/schemas/my-workflow/
-# Step 5: Edit schema.yaml and templates
-# No way to verify override is active
-# No way to diff against original
+# 步骤 5：编辑 schema.yaml 和模板
+# 无法验证覆盖是否处于活动状态
+# 升级 openspec 时无法与原始版本进行差异比较
```
-**Problems:**
-- Must know XDG path conventions
-- Finding npm package path varies by install method
-- No tooling to scaffold or verify
-- No diff capability when upgrading openspec
+**问题：**
+- 必须了解 XDG 路径约定
+- 查找 npm 包路径因安装方法而异
+- 没有工具来搭建或验证
+- 升级 openspec 时没有差异比较功能
---
-### Scenario 3: Team Sharing Custom Workflow
+### 场景 3：团队共享自定义工作流
-**Goal:** Team wants everyone to use the same custom schema.
+**目标：** 团队希望每个人都使用相同的自定义 schema。
-**Today's options:**
-1. Everyone manually sets up XDG override — error-prone, drift risk
-2. Document setup in README — still manual, easy to miss
-3. Publish separate npm package — overkill for most teams
-4. Check schema into repo — **not supported** (no project-local resolution)
+**今天的选项：**
+1. 每个人手动设置 XDG 覆盖 — 容易出错，存在漂移风险
+2. 在 README 中记录设置 — 仍然是手动的，容易遗漏
+3. 发布单独的 npm 包 — 对大多数团队来说过度
+4. 将 schema 检入仓库 — **不支持**（没有项目本地解析）
-**Problems:**
-- No project-local schema resolution
-- Can't version control custom schemas with the codebase
-- No single source of truth for team workflow
+**问题：**
+- 没有项目本地 schema 解析
+- 无法使用代码库对自定义 schema 进行版本控制
+- 团队工作流没有单一真实来源
---
-## Gap Summary
+## 差距摘要
-| Gap | Impact | Workaround |
+| 差距 | 影响 | 解决方法 |
|-----|--------|------------|
-| Schema not bound to change | Wrong results, forgotten context | Remember to pass `--schema` |
-| No project-local schemas | Can't share via repo | Manual XDG setup per machine |
-| No schema management CLI | Manual path hunting | Know XDG + find npm package |
-| No project default schema | Must specify every time | Always pass `--schema` |
-| No init-time schema selection | Missed setup opportunity | Manual config |
+| Schema 未绑定到变更 | 错误的结果，遗忘的上下文 | 记住传递 `--schema` |
+| 没有项目本地 schema | 无法通过仓库共享 | 每台机器手动设置 XDG |
+| 没有 schema 管理 CLI | 手动路径搜索 | 了解 XDG + 查找 npm 包 |
+| 没有项目默认 schema | 每次都必须指定 | 始终传递 `--schema` |
+| 没有初始化时的 schema 选择 | 错过设置机会 | 手动配置 |
---
-## Proposed Architecture
+## 提议的架构
-### New File Structure
+### 新文件结构
```
openspec/
-├── config.yaml # Project config (NEW)
-├── schemas/ # Project-local schemas (NEW)
+├── config.yaml # 项目配置（新）
+├── schemas/ # 项目本地 schema（新）
│ └── my-workflow/
│ ├── schema.yaml
│ └── templates/
@@ -140,241 +142,241 @@ openspec/
│ └── ...
└── changes/
└── add-auth/
- ├── change.yaml # Change metadata (NEW)
+ ├── change.yaml # 变更元数据（新）
├── proposal.md
└── ...
```
-### config.yaml (Project Config)
+### config.yaml（项目配置）
```yaml
# openspec/config.yaml
defaultSchema: spec-driven
```
-Sets the project-wide default schema. Used when:
-- Creating new changes without `--schema`
-- Running commands on changes without `change.yaml`
+设置项目范围的默认 schema。在以下情况下使用：
+- 创建没有 `--schema` 的新变更
+- 在没有 `change.yaml` 的变更上运行命令
-### change.yaml (Change Metadata)
+### change.yaml（变更元数据）
```yaml
# openspec/changes/add-auth/change.yaml
schema: tdd
created: 2025-01-15T10:30:00Z
-description: Add user authentication system
+description: 添加用户身份验证系统
```
-Binds a specific schema to a change. Created automatically by `openspec new change`.
+将特定 schema 绑定到变更。由 `openspec new change` 自动创建。
-### Schema Resolution Order
+### Schema 解析顺序
```
-1. ./openspec/schemas// # Project-local
-2. ~/.local/share/openspec/schemas// # User global (XDG)
-3. /schemas// # Built-in
+1. ./openspec/schemas// # 项目本地
+2. ~/.local/share/openspec/schemas// # 用户全局（XDG）
+3. /schemas// # 内置
```
-Project-local takes priority, enabling version-controlled custom schemas.
+项目本地优先，启用版本控制的自定义 schema。
-### Schema Selection Order (Per Command)
+### Schema 选择顺序（每个命令）
```
-1. --schema CLI flag # Explicit override
-2. change.yaml in change directory # Change-specific binding
-3. openspec/config.yaml defaultSchema # Project default
-4. "spec-driven" # Hardcoded fallback
+1. --schema CLI 标志 # 显式覆盖
+2. 变更目录中的 change.yaml # 特定于变更的绑定
+3. openspec/config.yaml defaultSchema # 项目默认
+4. "spec-driven" # 硬编码回退
```
---
-## Ideal User Experience
+## 理想的用户体验
-### Creating a Change
+### 创建变更
```bash
-# Uses project default (from config.yaml, or spec-driven)
+# 使用项目默认值（来自 config.yaml，或 spec-driven）
openspec new change add-auth
-# Creates openspec/changes/add-auth/change.yaml:
+# 创建 openspec/changes/add-auth/change.yaml：
# schema: spec-driven
# created: 2025-01-15T10:30:00Z
-# Explicit schema for this change
+# 此变更的显式 schema
openspec new change add-auth --schema tdd
-# Creates change.yaml with schema: tdd
+# 创建带有 schema: tdd 的 change.yaml
```
-### Working with Changes
+### 使用变更
```bash
-# Auto-reads schema from change.yaml — no --schema needed
+# 自动从 change.yaml 读取 schema — 不需要 --schema
openspec status --change add-auth
-# Output: "Change: add-auth (schema: tdd)"
+# 输出："Change: add-auth (schema: tdd)"
openspec next --change add-auth
-# Knows to use TDD artifacts
+# 知道使用 TDD 工件
-# Explicit override still works (with informational message)
+# 显式覆盖仍然有效（带有信息性消息）
openspec status --change add-auth --schema spec-driven
-# "Note: change.yaml specifies 'tdd', using 'spec-driven' per --schema flag"
+# "注意：change.yaml 指定 'tdd'，根据 --schema 标志使用 'spec-driven'"
```
-### Customizing Schemas
+### 自定义 Schema
```bash
-# See what's available
+# 查看可用内容
openspec schema list
-# Built-in:
+# 内置：
# spec-driven proposal → specs → design → tasks
# tdd spec → tests → implementation → docs
-# Project: (none)
-# User: (none)
+# 项目：（无）
+# 用户：（无）
-# Copy to project for customization
+# 复制到项目以进行自定义
openspec schema copy spec-driven my-workflow
-# Created ./openspec/schemas/my-workflow/
-# Edit schema.yaml and templates/ to customize
+# 创建 ./openspec/schemas/my-workflow/
+# 编辑 schema.yaml 和 templates/ 以自定义
-# Copy to global (user-level override)
+# 复制到全局（用户级覆盖）
openspec schema copy spec-driven --global
-# Created ~/.local/share/openspec/schemas/spec-driven/
+# 创建 ~/.local/share/openspec/schemas/spec-driven/
-# See where a schema resolves from
+# 查看 schema 从哪里解析
openspec schema which spec-driven
-# ./openspec/schemas/spec-driven/ (project)
-# or: ~/.local/share/openspec/schemas/spec-driven/ (user)
-# or: /usr/local/lib/node_modules/openspec/schemas/spec-driven/ (built-in)
+# ./openspec/schemas/spec-driven/ (项目)
+# 或：~/.local/share/openspec/schemas/spec-driven/ (用户)
+# 或：/usr/local/lib/node_modules/openspec/schemas/spec-driven/ (内置)
-# Compare override with built-in
+# 将覆盖与内置进行比较
openspec schema diff spec-driven
-# Shows diff between user/project version and package built-in
+# 显示用户/项目版本与包内置之间的差异
-# Remove override, revert to built-in
+# 删除覆盖，恢复到内置
openspec schema reset spec-driven
-# Removes ./openspec/schemas/spec-driven/ (or --global for user dir)
+# 删除 ./openspec/schemas/spec-driven/（或用于用户目录的 --global）
```
-### Project Setup
+### 项目设置
```bash
openspec init
-# ? Select default workflow schema:
+# ? 选择默认工作流 schema：
# > spec-driven (proposal → specs → design → tasks)
# tdd (spec → tests → implementation → docs)
-# (custom schemas if detected)
+# (如果检测到自定义 schema)
#
-# Writes to openspec/config.yaml:
+# 写入 openspec/config.yaml：
# defaultSchema: spec-driven
```
---
-## Implementation Phases
+## 实施阶段
-### Phase 1: Change Metadata (change.yaml)
+### 阶段 1：变更元数据（change.yaml）
-**Priority:** High
-**Solves:** "Forgot --schema", lost context, wrong results
+**优先级：** 高
+**解决：** "忘记 --schema"，丢失上下文，错误结果
-**Scope:**
-- Create `change.yaml` when running `openspec new change`
-- Store `schema`, `created` timestamp
-- Modify workflow commands to read schema from `change.yaml`
-- `--schema` flag overrides (with informational message)
-- Backwards compatible: missing `change.yaml` → use default
+**范围：**
+- 运行 `openspec new change` 时创建 `change.yaml`
+- 存储 `schema`、`created` 时间戳
+- 修改工作流命令以从 `change.yaml` 读取 schema
+- `--schema` 标志覆盖（带有信息性消息）
+- 向后兼容：缺少 `change.yaml` → 使用默认值
-**change.yaml format:**
+**change.yaml 格式：**
```yaml
schema: tdd
created: 2025-01-15T10:30:00Z
```
-**Migration:**
-- Existing changes without `change.yaml` continue to work
-- Default to `spec-driven` (current behavior)
-- Optional: `openspec migrate` to add `change.yaml` to existing changes
+**迁移：**
+- 没有 `change.yaml` 的现有变更继续工作
+- 默认为 `spec-driven`（当前行为）
+- 可选：`openspec migrate` 将 `change.yaml` 添加到现有变更
---
-### Phase 2: Project-Local Schemas
+### 阶段 2：项目本地 Schema
-**Priority:** High
-**Solves:** Team sharing, version control, no XDG knowledge needed
+**优先级：** 高
+**解决：** 团队共享，版本控制，不需要 XDG 知识
-**Scope:**
-- Add `./openspec/schemas/` to resolution order (first priority)
-- `openspec schema copy [new-name]` creates in project by default
-- `--global` flag for user-level XDG directory
-- Teams can commit `openspec/schemas/` to repo
+**范围：**
+- 将 `./openspec/schemas/` 添加到解析顺序（第一优先级）
+- `openspec schema copy [new-name]` 默认在项目中创建
+- 用于用户级 XDG 目录的 `--global` 标志
+- 团队可以将 `openspec/schemas/` 提交到仓库
-**Resolution order:**
+**解析顺序：**
```
-1. ./openspec/schemas// # Project-local (NEW)
-2. ~/.local/share/openspec/schemas// # User global
-3. /schemas// # Built-in
+1. ./openspec/schemas// # 项目本地（新）
+2. ~/.local/share/openspec/schemas// # 用户全局
+3. /schemas// # 内置
```
---
-### Phase 3: Schema Management CLI
+### 阶段 3：Schema 管理 CLI
-**Priority:** Medium
-**Solves:** Path discovery, scaffolding, debugging
+**优先级：** 中
+**解决：** 路径发现，脚手架，调试
-**Commands:**
+**命令：**
```bash
-openspec schema list # Show available schemas with sources
-openspec schema which # Show resolution path
-openspec schema copy [to] # Copy for customization
-openspec schema diff # Compare with built-in
-openspec schema reset # Remove override
-openspec schema validate # Validate schema.yaml structure
+openspec schema list # 显示带有来源的可用 schema
+openspec schema which # 显示解析路径
+openspec schema copy [to] # 复制以进行自定义
+openspec schema diff # 与内置比较
+openspec schema reset # 删除覆盖
+openspec schema validate # 验证 schema.yaml 结构
```
---
-### Phase 4: Project Config + Init Enhancement
+### 阶段 4：项目配置 + 初始化增强
-**Priority:** Low
-**Solves:** Project-wide defaults, streamlined setup
+**优先级：** 低
+**解决：** 项目范围的默认值，简化设置
-**Scope:**
-- Add `openspec/config.yaml` with `defaultSchema` field
-- `openspec init` prompts for schema selection
-- Store selection in `config.yaml`
-- Commands use as fallback when no `change.yaml` exists
+**范围：**
+- 添加带有 `defaultSchema` 字段的 `openspec/config.yaml`
+- `openspec init` 提示 schema 选择
+- 将选择存储在 `config.yaml` 中
+- 当不存在 `change.yaml` 时，命令使用作为回退
-**config.yaml format:**
+**config.yaml 格式：**
```yaml
defaultSchema: spec-driven
```
---
-## Backwards Compatibility
+## 向后兼容性
-| Scenario | Behavior |
+| 场景 | 行为 |
|----------|----------|
-| Existing change without `change.yaml` | Uses `--schema` flag or project default or `spec-driven` |
-| Existing project without `config.yaml` | Falls back to `spec-driven` |
-| `--schema` flag provided | Overrides `change.yaml` (with info message) |
-| No project-local schemas dir | Skipped in resolution, checks user/built-in |
+| 没有 `change.yaml` 的现有变更 | 使用 `--schema` 标志或项目默认值或 `spec-driven` |
+| 没有 `config.yaml` 的现有项目 | 回退到 `spec-driven` |
+| 提供 `--schema` 标志 | 覆盖 `change.yaml`（带有信息消息） |
+| 没有项目本地 schema 目录 | 在解析中跳过，检查用户/内置 |
-All existing functionality continues to work. New features are additive.
+所有现有功能继续工作。新功能是附加的。
---
-## Related Documents
+## 相关文档
-- [Schema Customization](./schema-customization.md) — Details on manual override process and CLI gaps
-- [Artifact POC](./artifact_poc.md) — Core artifact graph architecture
+- [Schema 自定义](./schema-customization.zh-CN.md) — 手动覆盖流程和 CLI 差距的详细信息
+- [工件 POC](./artifact_poc.zh-CN.md) — 核心工件图架构
-## Related Code
+## 相关代码
-| File | Purpose |
+| 文件 | 目的 |
|------|---------|
-| `src/core/artifact-graph/resolver.ts` | Schema resolution logic |
-| `src/core/artifact-graph/instruction-loader.ts` | Template loading |
-| `src/core/global-config.ts` | XDG path helpers |
-| `src/commands/artifact-workflow.ts` | CLI commands |
-| `src/utils/change-utils.ts` | Change creation utilities |
+| `src/core/artifact-graph/resolver.ts` | Schema 解析逻辑 |
+| `src/core/artifact-graph/instruction-loader.ts` | 模板加载 |
+| `src/core/global-config.ts` | XDG 路径助手 |
+| `src/commands/artifact-workflow.ts` | CLI 命令 |
+| `src/utils/change-utils.ts` | 变更创建实用程序 |
diff --git a/docs/schema-workflow-gaps.zh-CN.md b/docs/schema-workflow-gaps.zh-CN.md
new file mode 100644
index 00000000..48754dcc
--- /dev/null
+++ b/docs/schema-workflow-gaps.zh-CN.md
@@ -0,0 +1,382 @@
+# Schema 工作流：端到端分析
+
+本文档分析了在 OpenSpec 中使用 schema 的完整用户旅程，识别差距，并提出分阶段的解决方案。
+
+> [English Version](schema-workflow-gaps.md)
+
+---
+
+## 当前状态
+
+### 已存在的内容
+
+| 组件 | 状态 |
+|-----------|--------|
+| Schema 解析（XDG） | 2 级：用户覆盖 → 包内置 |
+| 内置 schema | `spec-driven`、`tdd` |
+| 工件工作流命令 | 带有 `--schema` 标志的 `status`、`next`、`instructions`、`templates` |
+| 变更创建 | `openspec new change ` — 没有 schema 绑定 |
+
+### 缺少的内容
+
+| 组件 | 状态 |
+|-----------|--------|
+| 绑定到变更的 Schema | 未存储 — 每次都必须传递 `--schema` |
+| 项目本地 schema | 不支持 — 无法使用仓库进行版本控制 |
+| Schema 管理 CLI | 无 — 需要手动路径发现 |
+| 项目默认 schema | 无 — 硬编码为 `spec-driven` |
+
+---
+
+## 用户旅程分析
+
+### 场景 1：使用非默认 Schema
+
+**目标：** 用户想为新功能使用 TDD 工作流。
+
+**今天的体验：**
+```bash
+openspec new change add-auth
+# 创建目录，未存储 schema 信息
+
+openspec status --change add-auth
+# 显示 spec-driven 工件（错误 - 用户想要 TDD）
+
+# 用户意识到错误...
+openspec status --change add-auth --schema tdd
+# 正确，但每次都必须记住 --schema
+
+# 6 个月后...
+openspec status --change add-auth
+# 又错了 - 没人记得这是 TDD
+```
+
+**问题：**
+- Schema 是运行时参数，未持久化
+- 容易忘记 `--schema` 并得到错误的结果
+- 没有记录预期的 schema 以供将来参考
+
+---
+
+### 场景 2：自定义 Schema
+
+**目标：** 用户想在"proposal"之前添加"research"工件。
+
+**今天的体验：**
+```bash
+# 步骤 1：弄清楚在哪里放置覆盖
+# 必须了解 XDG 约定：
+# macOS/Linux：~/.local/share/openspec/schemas/
+# Windows：%LOCALAPPDATA%\openspec\schemas/
+
+# 步骤 2：创建目录结构
+mkdir -p ~/.local/share/openspec/schemas/my-workflow/templates
+
+# 步骤 3：找到 npm 包以复制默认值
+npm list -g openspec --parseable
+# 输出因包管理器而异：
+# npm：/usr/local/lib/node_modules/openspec
+# pnpm：~/.local/share/pnpm/global/5/node_modules/openspec
+# volta：~/.volta/tools/image/packages/openspec/...
+# yarn：~/.config/yarn/global/node_modules/openspec
+
+# 步骤 4：复制文件
+cp -r /schemas/spec-driven/* \
+ ~/.local/share/openspec/schemas/my-workflow/
+
+# 步骤 5：编辑 schema.yaml 和模板
+# 无法验证覆盖是否处于活动状态
+# 升级 openspec 时无法与原始版本进行差异比较
+```
+
+**问题：**
+- 必须了解 XDG 路径约定
+- 查找 npm 包路径因安装方法而异
+- 没有工具来搭建或验证
+- 升级 openspec 时没有差异比较功能
+
+---
+
+### 场景 3：团队共享自定义工作流
+
+**目标：** 团队希望每个人都使用相同的自定义 schema。
+
+**今天的选项：**
+1. 每个人手动设置 XDG 覆盖 — 容易出错，存在漂移风险
+2. 在 README 中记录设置 — 仍然是手动的，容易遗漏
+3. 发布单独的 npm 包 — 对大多数团队来说过度
+4. 将 schema 检入仓库 — **不支持**（没有项目本地解析）
+
+**问题：**
+- 没有项目本地 schema 解析
+- 无法使用代码库对自定义 schema 进行版本控制
+- 团队工作流没有单一真实来源
+
+---
+
+## 差距摘要
+
+| 差距 | 影响 | 解决方法 |
+|-----|--------|------------|
+| Schema 未绑定到变更 | 错误的结果，遗忘的上下文 | 记住传递 `--schema` |
+| 没有项目本地 schema | 无法通过仓库共享 | 每台机器手动设置 XDG |
+| 没有 schema 管理 CLI | 手动路径搜索 | 了解 XDG + 查找 npm 包 |
+| 没有项目默认 schema | 每次都必须指定 | 始终传递 `--schema` |
+| 没有初始化时的 schema 选择 | 错过设置机会 | 手动配置 |
+
+---
+
+## 提议的架构
+
+### 新文件结构
+
+```
+openspec/
+├── config.yaml # 项目配置（新）
+├── schemas/ # 项目本地 schema（新）
+│ └── my-workflow/
+│ ├── schema.yaml
+│ └── templates/
+│ ├── research.md
+│ ├── proposal.md
+│ └── ...
+└── changes/
+ └── add-auth/
+ ├── change.yaml # 变更元数据（新）
+ ├── proposal.md
+ └── ...
+```
+
+### config.yaml（项目配置）
+
+```yaml
+# openspec/config.yaml
+defaultSchema: spec-driven
+```
+
+设置项目范围的默认 schema。在以下情况下使用：
+- 创建没有 `--schema` 的新变更
+- 在没有 `change.yaml` 的变更上运行命令
+
+### change.yaml（变更元数据）
+
+```yaml
+# openspec/changes/add-auth/change.yaml
+schema: tdd
+created: 2025-01-15T10:30:00Z
+description: 添加用户身份验证系统
+```
+
+将特定 schema 绑定到变更。由 `openspec new change` 自动创建。
+
+### Schema 解析顺序
+
+```
+1. ./openspec/schemas// # 项目本地
+2. ~/.local/share/openspec/schemas// # 用户全局（XDG）
+3. /schemas// # 内置
+```
+
+项目本地优先，启用版本控制的自定义 schema。
+
+### Schema 选择顺序（每个命令）
+
+```
+1. --schema CLI 标志 # 显式覆盖
+2. 变更目录中的 change.yaml # 特定于变更的绑定
+3. openspec/config.yaml defaultSchema # 项目默认
+4. "spec-driven" # 硬编码回退
+```
+
+---
+
+## 理想的用户体验
+
+### 创建变更
+
+```bash
+# 使用项目默认值（来自 config.yaml，或 spec-driven）
+openspec new change add-auth
+# 创建 openspec/changes/add-auth/change.yaml：
+# schema: spec-driven
+# created: 2025-01-15T10:30:00Z
+
+# 此变更的显式 schema
+openspec new change add-auth --schema tdd
+# 创建带有 schema: tdd 的 change.yaml
+```
+
+### 使用变更
+
+```bash
+# 自动从 change.yaml 读取 schema — 不需要 --schema
+openspec status --change add-auth
+# 输出："Change: add-auth (schema: tdd)"
+
+openspec next --change add-auth
+# 知道使用 TDD 工件
+
+# 显式覆盖仍然有效（带有信息性消息）
+openspec status --change add-auth --schema spec-driven
+# "注意：change.yaml 指定 'tdd'，根据 --schema 标志使用 'spec-driven'"
+```
+
+### 自定义 Schema
+
+```bash
+# 查看可用内容
+openspec schema list
+# 内置：
+# spec-driven proposal → specs → design → tasks
+# tdd spec → tests → implementation → docs
+# 项目：（无）
+# 用户：（无）
+
+# 复制到项目以进行自定义
+openspec schema copy spec-driven my-workflow
+# 创建 ./openspec/schemas/my-workflow/
+# 编辑 schema.yaml 和 templates/ 以自定义
+
+# 复制到全局（用户级覆盖）
+openspec schema copy spec-driven --global
+# 创建 ~/.local/share/openspec/schemas/spec-driven/
+
+# 查看 schema 从哪里解析
+openspec schema which spec-driven
+# ./openspec/schemas/spec-driven/ (项目)
+# 或：~/.local/share/openspec/schemas/spec-driven/ (用户)
+# 或：/usr/local/lib/node_modules/openspec/schemas/spec-driven/ (内置)
+
+# 将覆盖与内置进行比较
+openspec schema diff spec-driven
+# 显示用户/项目版本与包内置之间的差异
+
+# 删除覆盖，恢复到内置
+openspec schema reset spec-driven
+# 删除 ./openspec/schemas/spec-driven/（或用于用户目录的 --global）
+```
+
+### 项目设置
+
+```bash
+openspec init
+# ? 选择默认工作流 schema：
+# > spec-driven (proposal → specs → design → tasks)
+# tdd (spec → tests → implementation → docs)
+# (如果检测到自定义 schema)
+#
+# 写入 openspec/config.yaml：
+# defaultSchema: spec-driven
+```
+
+---
+
+## 实施阶段
+
+### 阶段 1：变更元数据（change.yaml）
+
+**优先级：** 高
+**解决：** "忘记 --schema"，丢失上下文，错误结果
+
+**范围：**
+- 运行 `openspec new change` 时创建 `change.yaml`
+- 存储 `schema`、`created` 时间戳
+- 修改工作流命令以从 `change.yaml` 读取 schema
+- `--schema` 标志覆盖（带有信息性消息）
+- 向后兼容：缺少 `change.yaml` → 使用默认值
+
+**change.yaml 格式：**
+```yaml
+schema: tdd
+created: 2025-01-15T10:30:00Z
+```
+
+**迁移：**
+- 没有 `change.yaml` 的现有变更继续工作
+- 默认为 `spec-driven`（当前行为）
+- 可选：`openspec migrate` 将 `change.yaml` 添加到现有变更
+
+---
+
+### 阶段 2：项目本地 Schema
+
+**优先级：** 高
+**解决：** 团队共享，版本控制，不需要 XDG 知识
+
+**范围：**
+- 将 `./openspec/schemas/` 添加到解析顺序（第一优先级）
+- `openspec schema copy [new-name]` 默认在项目中创建
+- 用于用户级 XDG 目录的 `--global` 标志
+- 团队可以将 `openspec/schemas/` 提交到仓库
+
+**解析顺序：**
+```
+1. ./openspec/schemas// # 项目本地（新）
+2. ~/.local/share/openspec/schemas// # 用户全局
+3. /schemas// # 内置
+```
+
+---
+
+### 阶段 3：Schema 管理 CLI
+
+**优先级：** 中
+**解决：** 路径发现，脚手架，调试
+
+**命令：**
+```bash
+openspec schema list # 显示带有来源的可用 schema
+openspec schema which # 显示解析路径
+openspec schema copy [to] # 复制以进行自定义
+openspec schema diff # 与内置比较
+openspec schema reset # 删除覆盖
+openspec schema validate # 验证 schema.yaml 结构
+```
+
+---
+
+### 阶段 4：项目配置 + 初始化增强
+
+**优先级：** 低
+**解决：** 项目范围的默认值，简化设置
+
+**范围：**
+- 添加带有 `defaultSchema` 字段的 `openspec/config.yaml`
+- `openspec init` 提示 schema 选择
+- 将选择存储在 `config.yaml` 中
+- 当不存在 `change.yaml` 时，命令使用作为回退
+
+**config.yaml 格式：**
+```yaml
+defaultSchema: spec-driven
+```
+
+---
+
+## 向后兼容性
+
+| 场景 | 行为 |
+|----------|----------|
+| 没有 `change.yaml` 的现有变更 | 使用 `--schema` 标志或项目默认值或 `spec-driven` |
+| 没有 `config.yaml` 的现有项目 | 回退到 `spec-driven` |
+| 提供 `--schema` 标志 | 覆盖 `change.yaml`（带有信息消息） |
+| 没有项目本地 schema 目录 | 在解析中跳过，检查用户/内置 |
+
+所有现有功能继续工作。新功能是附加的。
+
+---
+
+## 相关文档
+
+- [Schema 自定义](./schema-customization.zh-CN.md) — 手动覆盖流程和 CLI 差距的详细信息
+- [工件 POC](./artifact_poc.zh-CN.md) — 核心工件图架构
+
+## 相关代码
+
+| 文件 | 目的 |
+|------|---------|
+| `src/core/artifact-graph/resolver.ts` | Schema 解析逻辑 |
+| `src/core/artifact-graph/instruction-loader.ts` | 模板加载 |
+| `src/core/global-config.ts` | XDG 路径助手 |
+| `src/commands/artifact-workflow.ts` | CLI 命令 |
+| `src/utils/change-utils.ts` | 变更创建实用程序 |
diff --git a/openspec/AGENTS.md b/openspec/AGENTS.md
index 355969d8..25a1da6a 100644
--- a/openspec/AGENTS.md
+++ b/openspec/AGENTS.md
@@ -1,350 +1,352 @@
-# OpenSpec Instructions
-
-Instructions for AI coding assistants using OpenSpec for spec-driven development.
-
-## TL;DR Quick Checklist
-
-- Search existing work: `openspec spec list --long`, `openspec list` (use `rg` only for full-text search)
-- Decide scope: new capability vs modify existing capability
-- Pick a unique `change-id`: kebab-case, verb-led (`add-`, `update-`, `remove-`, `refactor-`)
-- Scaffold: `proposal.md`, `tasks.md`, `design.md` (only if needed), and delta specs per affected capability
-- Write deltas: use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements`; include at least one `#### Scenario:` per requirement
-- Validate: `openspec validate [change-id] --strict` and fix issues
-- Request approval: Do not start implementation until proposal is approved
-
-## Three-Stage Workflow
-
-### Stage 1: Creating Changes
-Create proposal when you need to:
-- Add features or functionality
-- Make breaking changes (API, schema)
-- Change architecture or patterns
-- Optimize performance (changes behavior)
-- Update security patterns
-
-Triggers (examples):
-- "Help me create a change proposal"
-- "Help me plan a change"
-- "Help me create a proposal"
-- "I want to create a spec proposal"
-- "I want to create a spec"
-
-Loose matching guidance:
-- Contains one of: `proposal`, `change`, `spec`
-- With one of: `create`, `plan`, `make`, `start`, `help`
-
-Skip proposal for:
-- Bug fixes (restore intended behavior)
-- Typos, formatting, comments
-- Dependency updates (non-breaking)
-- Configuration changes
-- Tests for existing behavior
-
-**Workflow**
-1. Review `openspec/project.md`, `openspec list`, and `openspec list --specs` to understand current context.
-2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, optional `design.md`, and spec deltas under `openspec/changes//`.
-3. Draft spec deltas using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement.
-4. Run `openspec validate --strict` and resolve any issues before sharing the proposal.
-
-### Stage 2: Implementing Changes
-Track these steps as TODOs and complete them one by one.
-1. **Read proposal.md** - Understand what's being built
-2. **Read design.md** (if exists) - Review technical decisions
-3. **Read tasks.md** - Get implementation checklist
-4. **Implement tasks sequentially** - Complete in order
-5. **Confirm completion** - Ensure every item in `tasks.md` is finished before updating statuses
-6. **Update checklist** - After all work is done, set every task to `- [x]` so the list reflects reality
-7. **Approval gate** - Do not start implementation until the proposal is reviewed and approved
-
-### Stage 3: Archiving Changes
-After deployment, create separate PR to:
-- Move `changes/[name]/` → `changes/archive/YYYY-MM-DD-[name]/`
-- Update `specs/` if capabilities changed
-- Use `openspec archive --skip-specs --yes` for tooling-only changes (always pass the change ID explicitly)
-- Run `openspec validate --strict` to confirm the archived change passes checks
-
-## Before Any Task
-
-**Context Checklist:**
-- [ ] Read relevant specs in `specs/[capability]/spec.md`
-- [ ] Check pending changes in `changes/` for conflicts
-- [ ] Read `openspec/project.md` for conventions
-- [ ] Run `openspec list` to see active changes
-- [ ] Run `openspec list --specs` to see existing capabilities
-
-**Before Creating Specs:**
-- Always check if capability already exists
-- Prefer modifying existing specs over creating duplicates
-- Use `openspec show [spec]` to review current state
-- If request is ambiguous, ask 1–2 clarifying questions before scaffolding
-
-### Search Guidance
-- Enumerate specs: `openspec spec list --long` (or `--json` for scripts)
-- Enumerate changes: `openspec list` (or `openspec change list --json` - deprecated but available)
-- Show details:
- - Spec: `openspec show --type spec` (use `--json` for filters)
- - Change: `openspec show --json --deltas-only`
-- Full-text search (use ripgrep): `rg -n "Requirement:|Scenario:" openspec/specs`
-
-## Quick Start
-
-### CLI Commands
+# OpenSpec 指令
+
+为使用 OpenSpec 进行规范驱动开发的 AI 编码助手提供的指令。
+
+> [English Version](AGENTS.md)
+
+## TL;DR 快速检查清单
+
+- 搜索现有工作：`openspec spec list --long`、`openspec list`（仅使用 `rg` 进行全文搜索）
+- 决定范围：新功能 vs 修改现有功能
+- 选择唯一的 `change-id`：kebab-case，动词引导（`add-`、`update-`、`remove-`、`refactor-`）
+- 搭建：`proposal.md`、`tasks.md`、`design.md`（仅在需要时）以及每个受影响功能的增量规范
+- 编写增量：使用 `## ADDED|MODIFIED|REMOVED|RENAMED Requirements`；每个需求至少包含一个 `#### Scenario:`
+- 验证：`openspec validate [change-id] --strict` 并修复问题
+- 请求批准：在提案获得批准之前不要开始实施
+
+## 三阶段工作流
+
+### 阶段 1：创建变更
+在以下情况下创建提案：
+- 添加功能或特性
+- 进行破坏性变更（API、模式）
+- 更改架构或模式
+- 优化性能（改变行为）
+- 更新安全模式
+
+触发器（示例）：
+- "帮我创建一个变更提案"
+- "帮我规划一个变更"
+- "帮我创建一个提案"
+- "我想创建一个规范提案"
+- "我想创建一个规范"
+
+宽松匹配指导：
+- 包含以下之一：`proposal`、`change`、`spec`
+- 以及以下之一：`create`、`plan`、`make`、`start`、`help`
+
+跳过提案的情况：
+- 错误修复（恢复预期行为）
+- 拼写错误、格式、注释
+- 依赖项更新（非破坏性）
+- 配置更改
+- 现有行为的测试
+
+**工作流**
+1. 查看 `openspec/project.md`、`openspec list` 和 `openspec list --specs` 以了解当前上下文。
+2. 选择唯一的动词引导的 `change-id` 并在 `openspec/changes//` 下搭建 `proposal.md`、`tasks.md`、可选的 `design.md` 和规范增量。
+3. 使用 `## ADDED|MODIFIED|REMOVED Requirements` 起草规范增量，每个需求至少包含一个 `#### Scenario:`。
+4. 运行 `openspec validate --strict` 并在分享提案之前解决任何问题。
+
+### 阶段 2：实施变更
+将这些步骤作为待办事项跟踪并逐一完成。
+1. **阅读 proposal.md** - 了解正在构建什么
+2. **阅读 design.md**（如果存在）- 审查技术决策
+3. **阅读 tasks.md** - 获取实施清单
+4. **按顺序实施任务** - 按顺序完成
+5. **确认完成** - 在更新状态之前确保 `tasks.md` 中的每个项目都已完成
+6. **更新清单** - 所有工作完成后，将每个任务设置为 `- [x]`，以便列表反映实际情况
+7. **批准门** - 在提案经过审查和批准之前不要开始实施
+
+### 阶段 3：归档变更
+部署后，创建单独的 PR 以：
+- 移动 `changes/[name]/` → `changes/archive/YYYY-MM-DD-[name]/`
+- 如果功能发生变化，更新 `specs/`
+- 对于仅工具变更，使用 `openspec archive --skip-specs --yes`（始终明确传递变更 ID）
+- 运行 `openspec validate --strict` 以确认归档的变更通过检查
+
+## 任何任务之前
+
+**上下文检查清单：**
+- [ ] 阅读 `specs/[capability]/spec.md` 中的相关规范
+- [ ] 检查 `changes/` 中的待处理变更是否存在冲突
+- [ ] 阅读 `openspec/project.md` 了解约定
+- [ ] 运行 `openspec list` 查看活跃的变更
+- [ ] 运行 `openspec list --specs` 查看现有功能
+
+**创建规范之前：**
+- 始终检查功能是否已存在
+- 优先修改现有规范而不是创建重复项
+- 使用 `openspec show [spec]` 审查当前状态
+- 如果请求模糊，在搭建之前提出 1-2 个澄清问题
+
+### 搜索指导
+- 枚举规范：`openspec spec list --long`（或 `--json` 用于脚本）
+- 枚举变更：`openspec list`（或 `openspec change list --json` - 已弃用但可用）
+- 显示详细信息：
+ - 规范：`openspec show --type spec`（使用 `--json` 进行过滤）
+ - 变更：`openspec show --json --deltas-only`
+- 全文搜索（使用 ripgrep）：`rg -n "Requirement:|Scenario:" openspec/specs`
+
+## 快速开始
+
+### CLI 命令
```bash
-# Essential commands
-openspec list # List active changes
-openspec list --specs # List specifications
-openspec show [item] # Display change or spec
-openspec validate [item] # Validate changes or specs
-openspec archive [--yes|-y] # Archive after deployment (add --yes for non-interactive runs)
-
-# Project management
-openspec init [path] # Initialize OpenSpec
-openspec update [path] # Update instruction files
-
-# Interactive mode
-openspec show # Prompts for selection
-openspec validate # Bulk validation mode
-
-# Debugging
+# 基本命令
+openspec list # 列出活跃的变更
+openspec list --specs # 列出规范
+openspec show [item] # 显示变更或规范
+openspec validate [item] # 验证变更或规范
+openspec archive [--yes|-y] # 部署后归档（添加 --yes 进行非交互式运行）
+
+# 项目管理
+openspec init [path] # 初始化 OpenSpec
+openspec update [path] # 更新指令文件
+
+# 交互模式
+openspec show # 提示选择
+openspec validate # 批量验证模式
+
+# 调试
openspec show [change] --json --deltas-only
openspec validate [change] --strict
```
-### Command Flags
+### 命令标志
-- `--json` - Machine-readable output
-- `--type change|spec` - Disambiguate items
-- `--strict` - Comprehensive validation
-- `--no-interactive` - Disable prompts
-- `--skip-specs` - Archive without spec updates
-- `--yes`/`-y` - Skip confirmation prompts (non-interactive archive)
+- `--json` - 机器可读输出
+- `--type change|spec` - 消除项目歧义
+- `--strict` - 全面验证
+- `--no-interactive` - 禁用提示
+- `--skip-specs` - 归档时不更新规范
+- `--yes`/`-y` - 跳过确认提示（非交互式归档）
-## Directory Structure
+## 目录结构
```
openspec/
-├── project.md # Project conventions
-├── specs/ # Current truth - what IS built
-│ └── [capability]/ # Single focused capability
-│ ├── spec.md # Requirements and scenarios
-│ └── design.md # Technical patterns
-├── changes/ # Proposals - what SHOULD change
+├── project.md # 项目约定
+├── specs/ # 当前真实状态 - 已构建的内容
+│ └── [capability]/ # 单一聚焦的功能
+│ ├── spec.md # 需求和场景
+│ └── design.md # 技术模式
+├── changes/ # 提案 - 应该改变的内容
│ ├── [change-name]/
-│ │ ├── proposal.md # Why, what, impact
-│ │ ├── tasks.md # Implementation checklist
-│ │ ├── design.md # Technical decisions (optional; see criteria)
-│ │ └── specs/ # Delta changes
+│ │ ├── proposal.md # 为什么、什么、影响
+│ │ ├── tasks.md # 实施清单
+│ │ ├── design.md # 技术决策（可选；见标准）
+│ │ └── specs/ # 增量变更
│ │ └── [capability]/
│ │ └── spec.md # ADDED/MODIFIED/REMOVED
-│ └── archive/ # Completed changes
+│ └── archive/ # 已完成的变更
```
-## Creating Change Proposals
+## 创建变更提案
-### Decision Tree
+### 决策树
```
-New request?
-├─ Bug fix restoring spec behavior? → Fix directly
-├─ Typo/format/comment? → Fix directly
-├─ New feature/capability? → Create proposal
-├─ Breaking change? → Create proposal
-├─ Architecture change? → Create proposal
-└─ Unclear? → Create proposal (safer)
+新请求？
+├─ 恢复规范行为的错误修复？ → 直接修复
+├─ 拼写错误/格式/注释？ → 直接修复
+├─ 新功能/能力？ → 创建提案
+├─ 破坏性变更？ → 创建提案
+├─ 架构变更？ → 创建提案
+└─ 不清楚？ → 创建提案（更安全）
```
-### Proposal Structure
+### 提案结构
-1. **Create directory:** `changes/[change-id]/` (kebab-case, verb-led, unique)
+1. **创建目录：** `changes/[change-id]/`（kebab-case，动词引导，唯一）
-2. **Write proposal.md:**
+2. **编写 proposal.md：**
```markdown
## Why
-[1-2 sentences on problem/opportunity]
+[关于问题/机会的 1-2 句话]
## What Changes
-- [Bullet list of changes]
-- [Mark breaking changes with **BREAKING**]
+- [变更的项目符号列表]
+- [用 **BREAKING** 标记破坏性变更]
## Impact
-- Affected specs: [list capabilities]
-- Affected code: [key files/systems]
+- 受影响的规范：[列出功能]
+- 受影响的代码：[关键文件/系统]
```
-3. **Create spec deltas:** `specs/[capability]/spec.md`
+3. **创建规范增量：** `specs/[capability]/spec.md`
```markdown
## ADDED Requirements
### Requirement: New Feature
-The system SHALL provide...
+系统应提供...
#### Scenario: Success case
-- **WHEN** user performs action
-- **THEN** expected result
+- **WHEN** 用户执行操作
+- **THEN** 预期结果
## MODIFIED Requirements
### Requirement: Existing Feature
-[Complete modified requirement]
+[完整的修改需求]
## REMOVED Requirements
### Requirement: Old Feature
-**Reason**: [Why removing]
-**Migration**: [How to handle]
+**Reason**: [为什么删除]
+**Migration**: [如何处理]
```
-If multiple capabilities are affected, create multiple delta files under `changes/[change-id]/specs//spec.md`—one per capability.
+如果多个功能受到影响，在 `changes/[change-id]/specs//spec.md` 下创建多个增量文件——每个功能一个。
-4. **Create tasks.md:**
+4. **创建 tasks.md：**
```markdown
## 1. Implementation
-- [ ] 1.1 Create database schema
-- [ ] 1.2 Implement API endpoint
-- [ ] 1.3 Add frontend component
-- [ ] 1.4 Write tests
+- [ ] 1.1 创建数据库模式
+- [ ] 1.2 实施 API 端点
+- [ ] 1.3 添加前端组件
+- [ ] 1.4 编写测试
```
-5. **Create design.md when needed:**
-Create `design.md` if any of the following apply; otherwise omit it:
-- Cross-cutting change (multiple services/modules) or a new architectural pattern
-- New external dependency or significant data model changes
-- Security, performance, or migration complexity
-- Ambiguity that benefits from technical decisions before coding
+5. **在需要时创建 design.md：**
+如果以下任何一项适用，则创建 `design.md`；否则省略：
+- 跨领域变更（多个服务/模块）或新的架构模式
+- 新的外部依赖项或重大数据模型变更
+- 安全性、性能或迁移复杂性
+- 在编码之前从技术决策中受益的模糊性
-Minimal `design.md` skeleton:
+最小的 `design.md` 骨架：
```markdown
## Context
-[Background, constraints, stakeholders]
+[背景、约束、利益相关者]
## Goals / Non-Goals
- Goals: [...]
- Non-Goals: [...]
## Decisions
-- Decision: [What and why]
-- Alternatives considered: [Options + rationale]
+- Decision: [什么和为什么]
+- Alternatives considered: [选项 + 理由]
## Risks / Trade-offs
-- [Risk] → Mitigation
+- [风险] → 缓解措施
## Migration Plan
-[Steps, rollback]
+[步骤、回滚]
## Open Questions
- [...]
```
-## Spec File Format
+## 规范文件格式
-### Critical: Scenario Formatting
+### 关键：场景格式
-**CORRECT** (use #### headers):
+**正确**（使用 #### 标题）：
```markdown
#### Scenario: User login success
-- **WHEN** valid credentials provided
-- **THEN** return JWT token
+- **WHEN** 提供有效凭据
+- **THEN** 返回 JWT 令牌
```
-**WRONG** (don't use bullets or bold):
+**错误**（不要使用项目符号或粗体）：
```markdown
- **Scenario: User login** ❌
**Scenario**: User login ❌
### Scenario: User login ❌
```
-Every requirement MUST have at least one scenario.
+每个需求必须至少有一个场景。
-### Requirement Wording
-- Use SHALL/MUST for normative requirements (avoid should/may unless intentionally non-normative)
+### 需求措辞
+- 对规范性需求使用 SHALL/MUST（除非有意为非规范性，否则避免使用 should/may）
-### Delta Operations
+### 增量操作
-- `## ADDED Requirements` - New capabilities
-- `## MODIFIED Requirements` - Changed behavior
-- `## REMOVED Requirements` - Deprecated features
-- `## RENAMED Requirements` - Name changes
+- `## ADDED Requirements` - 新功能
+- `## MODIFIED Requirements` - 更改的行为
+- `## REMOVED Requirements` - 已弃用的功能
+- `## RENAMED Requirements` - 名称更改
-Headers matched with `trim(header)` - whitespace ignored.
+标题使用 `trim(header)` 匹配 - 忽略空格。
-#### When to use ADDED vs MODIFIED
-- ADDED: Introduces a new capability or sub-capability that can stand alone as a requirement. Prefer ADDED when the change is orthogonal (e.g., adding "Slash Command Configuration") rather than altering the semantics of an existing requirement.
-- MODIFIED: Changes the behavior, scope, or acceptance criteria of an existing requirement. Always paste the full, updated requirement content (header + all scenarios). The archiver will replace the entire requirement with what you provide here; partial deltas will drop previous details.
-- RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content) referencing the new name.
+#### 何时使用 ADDED vs MODIFIED
+- ADDED：引入可以作为需求独立存在的新功能或子功能。当变更是正交的（例如，添加"斜杠命令配置"）而不是改变现有需求的语义时，优先使用 ADDED。
+- MODIFIED：更改现有需求的行为、范围或验收标准。始终粘贴完整的、更新的需求内容（标题 + 所有场景）。归档器将用您在此处提供的内容替换整个需求；部分增量将丢弃以前的详细信息。
+- RENAMED：仅在名称更改时使用。如果您还更改了行为，请使用 RENAMED（名称）加上引用新名称的 MODIFIED（内容）。
-Common pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at archive time. If you aren’t explicitly changing the existing requirement, add a new requirement under ADDED instead.
+常见陷阱：使用 MODIFIED 添加新关注点而不包括以前的文本。这会在归档时导致详细信息丢失。如果您没有明确更改现有需求，请在 ADDED 下添加新需求。
-Authoring a MODIFIED requirement correctly:
-1) Locate the existing requirement in `openspec/specs//spec.md`.
-2) Copy the entire requirement block (from `### Requirement: ...` through its scenarios).
-3) Paste it under `## MODIFIED Requirements` and edit to reflect the new behavior.
-4) Ensure the header text matches exactly (whitespace-insensitive) and keep at least one `#### Scenario:`.
+正确编写 MODIFIED 需求：
+1) 在 `openspec/specs//spec.md` 中找到现有需求。
+2) 复制整个需求块（从 `### Requirement: ...` 到其场景）。
+3) 将其粘贴到 `## MODIFIED Requirements` 下并编辑以反映新行为。
+4) 确保标题文本完全匹配（不区分空格）并保留至少一个 `#### Scenario:`。
-Example for RENAMED:
+RENAMED 示例：
```markdown
## RENAMED Requirements
- FROM: `### Requirement: Login`
- TO: `### Requirement: User Authentication`
```
-## Troubleshooting
+## 故障排除
-### Common Errors
+### 常见错误
**"Change must have at least one delta"**
-- Check `changes/[name]/specs/` exists with .md files
-- Verify files have operation prefixes (## ADDED Requirements)
+- 检查 `changes/[name]/specs/` 是否存在 .md 文件
+- 验证文件是否有操作前缀（## ADDED Requirements）
**"Requirement must have at least one scenario"**
-- Check scenarios use `#### Scenario:` format (4 hashtags)
-- Don't use bullet points or bold for scenario headers
+- 检查场景是否使用 `#### Scenario:` 格式（4 个井号）
+- 不要对场景标题使用项目符号或粗体
-**Silent scenario parsing failures**
-- Exact format required: `#### Scenario: Name`
-- Debug with: `openspec show [change] --json --deltas-only`
+**静默场景解析失败**
+- 需要精确格式：`#### Scenario: Name`
+- 使用以下命令调试：`openspec show [change] --json --deltas-only`
-### Validation Tips
+### 验证提示
```bash
-# Always use strict mode for comprehensive checks
+# 始终使用严格模式进行全面检查
openspec validate [change] --strict
-# Debug delta parsing
+# 调试增量解析
openspec show [change] --json | jq '.deltas'
-# Check specific requirement
+# 检查特定需求
openspec show [spec] --json -r 1
```
-## Happy Path Script
+## 快乐路径脚本
```bash
-# 1) Explore current state
+# 1) 探索当前状态
openspec spec list --long
openspec list
-# Optional full-text search:
+# 可选的全文搜索：
# rg -n "Requirement:|Scenario:" openspec/specs
# rg -n "^#|Requirement:" openspec/changes
-# 2) Choose change id and scaffold
+# 2) 选择变更 id 并搭建
CHANGE=add-two-factor-auth
mkdir -p openspec/changes/$CHANGE/{specs/auth}
printf "## Why\n...\n\n## What Changes\n- ...\n\n## Impact\n- ...\n" > openspec/changes/$CHANGE/proposal.md
printf "## 1. Implementation\n- [ ] 1.1 ...\n" > openspec/changes/$CHANGE/tasks.md
-# 3) Add deltas (example)
+# 3) 添加增量（示例）
cat > openspec/changes/$CHANGE/specs/auth/spec.md << 'EOF'
## ADDED Requirements
### Requirement: Two-Factor Authentication
-Users MUST provide a second factor during login.
+用户必须在登录期间提供第二因素。
#### Scenario: OTP required
-- **WHEN** valid credentials are provided
-- **THEN** an OTP challenge is required
+- **WHEN** 提供有效凭据
+- **THEN** 需要 OTP 挑战
EOF
-# 4) Validate
+# 4) 验证
openspec validate $CHANGE --strict
```
-## Multi-Capability Example
+## 多功能示例
```
openspec/changes/add-2fa-notify/
@@ -371,84 +373,84 @@ notifications/spec.md
...
```
-## Best Practices
+## 最佳实践
-### Simplicity First
-- Default to <100 lines of new code
-- Single-file implementations until proven insufficient
-- Avoid frameworks without clear justification
-- Choose boring, proven patterns
+### 简单优先
+- 默认为 <100 行新代码
+- 单文件实现，直到证明不足
+- 避免没有明确理由的框架
+- 选择无聊的、经过验证的模式
-### Complexity Triggers
-Only add complexity with:
-- Performance data showing current solution too slow
-- Concrete scale requirements (>1000 users, >100MB data)
-- Multiple proven use cases requiring abstraction
+### 复杂性触发器
+仅在以下情况下添加复杂性：
+- 性能数据显示当前解决方案太慢
+- 具体的规模要求（>1000 用户，>100MB 数据）
+- 需要抽象的多个经过验证的用例
-### Clear References
-- Use `file.ts:42` format for code locations
-- Reference specs as `specs/auth/spec.md`
-- Link related changes and PRs
+### 清晰的引用
+- 使用 `file.ts:42` 格式表示代码位置
+- 将规范引用为 `specs/auth/spec.md`
+- 链接相关变更和 PR
-### Capability Naming
-- Use verb-noun: `user-auth`, `payment-capture`
-- Single purpose per capability
-- 10-minute understandability rule
-- Split if description needs "AND"
+### 功能命名
+- 使用动词-名词：`user-auth`、`payment-capture`
+- 每个功能单一目的
+- 10 分钟可理解性规则
+- 如果描述需要"AND"，则拆分
-### Change ID Naming
-- Use kebab-case, short and descriptive: `add-two-factor-auth`
-- Prefer verb-led prefixes: `add-`, `update-`, `remove-`, `refactor-`
-- Ensure uniqueness; if taken, append `-2`, `-3`, etc.
+### 变更 ID 命名
+- 使用 kebab-case，简短且描述性：`add-two-factor-auth`
+- 优先使用动词引导的前缀：`add-`、`update-`、`remove-`、`refactor-`
+- 确保唯一性；如果已占用，追加 `-2`、`-3` 等
-## Tool Selection Guide
+## 工具选择指南
-| Task | Tool | Why |
+| 任务 | 工具 | 原因 |
|------|------|-----|
-| Find files by pattern | Glob | Fast pattern matching |
-| Search code content | Grep | Optimized regex search |
-| Read specific files | Read | Direct file access |
-| Explore unknown scope | Task | Multi-step investigation |
-
-## Error Recovery
-
-### Change Conflicts
-1. Run `openspec list` to see active changes
-2. Check for overlapping specs
-3. Coordinate with change owners
-4. Consider combining proposals
-
-### Validation Failures
-1. Run with `--strict` flag
-2. Check JSON output for details
-3. Verify spec file format
-4. Ensure scenarios properly formatted
-
-### Missing Context
-1. Read project.md first
-2. Check related specs
-3. Review recent archives
-4. Ask for clarification
-
-## Quick Reference
-
-### Stage Indicators
-- `changes/` - Proposed, not yet built
-- `specs/` - Built and deployed
-- `archive/` - Completed changes
-
-### File Purposes
-- `proposal.md` - Why and what
-- `tasks.md` - Implementation steps
-- `design.md` - Technical decisions
-- `spec.md` - Requirements and behavior
-
-### CLI Essentials
+| 按模式查找文件 | Glob | 快速模式匹配 |
+| 搜索代码内容 | Grep | 优化的正则表达式搜索 |
+| 读取特定文件 | Read | 直接文件访问 |
+| 探索未知范围 | Task | 多步骤调查 |
+
+## 错误恢复
+
+### 变更冲突
+1. 运行 `openspec list` 查看活跃的变更
+2. 检查重叠的规范
+3. 与变更所有者协调
+4. 考虑合并提案
+
+### 验证失败
+1. 使用 `--strict` 标志运行
+2. 检查 JSON 输出以获取详细信息
+3. 验证规范文件格式
+4. 确保场景格式正确
+
+### 缺少上下文
+1. 首先阅读 project.md
+2. 检查相关规范
+3. 审查最近的归档
+4. 寻求澄清
+
+## 快速参考
+
+### 阶段指示器
+- `changes/` - 提议的，尚未构建
+- `specs/` - 已构建和部署
+- `archive/` - 已完成的变更
+
+### 文件目的
+- `proposal.md` - 为什么和什么
+- `tasks.md` - 实施步骤
+- `design.md` - 技术决策
+- `spec.md` - 需求和行为
+
+### CLI 要点
```bash
-openspec list # What's in progress?
-openspec show [item] # View details
-openspec validate --strict # Is it correct?
-openspec archive [--yes|-y] # Mark complete (add --yes for automation)
+openspec list # 正在进行什么？
+openspec show [item] # 查看详细信息
+openspec validate --strict # 是否正确？
+openspec archive [--yes|-y] # 标记完成（添加 --yes 进行自动化）
```
-Remember: Specs are truth. Changes are proposals. Keep them in sync.
+记住：规范是真实的。变更是提案。保持它们同步。
diff --git a/openspec/AGENTS.zh-CN.md b/openspec/AGENTS.zh-CN.md
new file mode 100644
index 00000000..25a1da6a
--- /dev/null
+++ b/openspec/AGENTS.zh-CN.md
@@ -0,0 +1,456 @@
+# OpenSpec 指令
+
+为使用 OpenSpec 进行规范驱动开发的 AI 编码助手提供的指令。
+
+> [English Version](AGENTS.md)
+
+## TL;DR 快速检查清单
+
+- 搜索现有工作：`openspec spec list --long`、`openspec list`（仅使用 `rg` 进行全文搜索）
+- 决定范围：新功能 vs 修改现有功能
+- 选择唯一的 `change-id`：kebab-case，动词引导（`add-`、`update-`、`remove-`、`refactor-`）
+- 搭建：`proposal.md`、`tasks.md`、`design.md`（仅在需要时）以及每个受影响功能的增量规范
+- 编写增量：使用 `## ADDED|MODIFIED|REMOVED|RENAMED Requirements`；每个需求至少包含一个 `#### Scenario:`
+- 验证：`openspec validate [change-id] --strict` 并修复问题
+- 请求批准：在提案获得批准之前不要开始实施
+
+## 三阶段工作流
+
+### 阶段 1：创建变更
+在以下情况下创建提案：
+- 添加功能或特性
+- 进行破坏性变更（API、模式）
+- 更改架构或模式
+- 优化性能（改变行为）
+- 更新安全模式
+
+触发器（示例）：
+- "帮我创建一个变更提案"
+- "帮我规划一个变更"
+- "帮我创建一个提案"
+- "我想创建一个规范提案"
+- "我想创建一个规范"
+
+宽松匹配指导：
+- 包含以下之一：`proposal`、`change`、`spec`
+- 以及以下之一：`create`、`plan`、`make`、`start`、`help`
+
+跳过提案的情况：
+- 错误修复（恢复预期行为）
+- 拼写错误、格式、注释
+- 依赖项更新（非破坏性）
+- 配置更改
+- 现有行为的测试
+
+**工作流**
+1. 查看 `openspec/project.md`、`openspec list` 和 `openspec list --specs` 以了解当前上下文。
+2. 选择唯一的动词引导的 `change-id` 并在 `openspec/changes//` 下搭建 `proposal.md`、`tasks.md`、可选的 `design.md` 和规范增量。
+3. 使用 `## ADDED|MODIFIED|REMOVED Requirements` 起草规范增量，每个需求至少包含一个 `#### Scenario:`。
+4. 运行 `openspec validate --strict` 并在分享提案之前解决任何问题。
+
+### 阶段 2：实施变更
+将这些步骤作为待办事项跟踪并逐一完成。
+1. **阅读 proposal.md** - 了解正在构建什么
+2. **阅读 design.md**（如果存在）- 审查技术决策
+3. **阅读 tasks.md** - 获取实施清单
+4. **按顺序实施任务** - 按顺序完成
+5. **确认完成** - 在更新状态之前确保 `tasks.md` 中的每个项目都已完成
+6. **更新清单** - 所有工作完成后，将每个任务设置为 `- [x]`，以便列表反映实际情况
+7. **批准门** - 在提案经过审查和批准之前不要开始实施
+
+### 阶段 3：归档变更
+部署后，创建单独的 PR 以：
+- 移动 `changes/[name]/` → `changes/archive/YYYY-MM-DD-[name]/`
+- 如果功能发生变化，更新 `specs/`
+- 对于仅工具变更，使用 `openspec archive --skip-specs --yes`（始终明确传递变更 ID）
+- 运行 `openspec validate --strict` 以确认归档的变更通过检查
+
+## 任何任务之前
+
+**上下文检查清单：**
+- [ ] 阅读 `specs/[capability]/spec.md` 中的相关规范
+- [ ] 检查 `changes/` 中的待处理变更是否存在冲突
+- [ ] 阅读 `openspec/project.md` 了解约定
+- [ ] 运行 `openspec list` 查看活跃的变更
+- [ ] 运行 `openspec list --specs` 查看现有功能
+
+**创建规范之前：**
+- 始终检查功能是否已存在
+- 优先修改现有规范而不是创建重复项
+- 使用 `openspec show [spec]` 审查当前状态
+- 如果请求模糊，在搭建之前提出 1-2 个澄清问题
+
+### 搜索指导
+- 枚举规范：`openspec spec list --long`（或 `--json` 用于脚本）
+- 枚举变更：`openspec list`（或 `openspec change list --json` - 已弃用但可用）
+- 显示详细信息：
+ - 规范：`openspec show --type spec`（使用 `--json` 进行过滤）
+ - 变更：`openspec show --json --deltas-only`
+- 全文搜索（使用 ripgrep）：`rg -n "Requirement:|Scenario:" openspec/specs`
+
+## 快速开始
+
+### CLI 命令
+
+```bash
+# 基本命令
+openspec list # 列出活跃的变更
+openspec list --specs # 列出规范
+openspec show [item] # 显示变更或规范
+openspec validate [item] # 验证变更或规范
+openspec archive [--yes|-y] # 部署后归档（添加 --yes 进行非交互式运行）
+
+# 项目管理
+openspec init [path] # 初始化 OpenSpec
+openspec update [path] # 更新指令文件
+
+# 交互模式
+openspec show # 提示选择
+openspec validate # 批量验证模式
+
+# 调试
+openspec show [change] --json --deltas-only
+openspec validate [change] --strict
+```
+
+### 命令标志
+
+- `--json` - 机器可读输出
+- `--type change|spec` - 消除项目歧义
+- `--strict` - 全面验证
+- `--no-interactive` - 禁用提示
+- `--skip-specs` - 归档时不更新规范
+- `--yes`/`-y` - 跳过确认提示（非交互式归档）
+
+## 目录结构
+
+```
+openspec/
+├── project.md # 项目约定
+├── specs/ # 当前真实状态 - 已构建的内容
+│ └── [capability]/ # 单一聚焦的功能
+│ ├── spec.md # 需求和场景
+│ └── design.md # 技术模式
+├── changes/ # 提案 - 应该改变的内容
+│ ├── [change-name]/
+│ │ ├── proposal.md # 为什么、什么、影响
+│ │ ├── tasks.md # 实施清单
+│ │ ├── design.md # 技术决策（可选；见标准）
+│ │ └── specs/ # 增量变更
+│ │ └── [capability]/
+│ │ └── spec.md # ADDED/MODIFIED/REMOVED
+│ └── archive/ # 已完成的变更
+```
+
+## 创建变更提案
+
+### 决策树
+
+```
+新请求？
+├─ 恢复规范行为的错误修复？ → 直接修复
+├─ 拼写错误/格式/注释？ → 直接修复
+├─ 新功能/能力？ → 创建提案
+├─ 破坏性变更？ → 创建提案
+├─ 架构变更？ → 创建提案
+└─ 不清楚？ → 创建提案（更安全）
+```
+
+### 提案结构
+
+1. **创建目录：** `changes/[change-id]/`（kebab-case，动词引导，唯一）
+
+2. **编写 proposal.md：**
+```markdown
+## Why
+[关于问题/机会的 1-2 句话]
+
+## What Changes
+- [变更的项目符号列表]
+- [用 **BREAKING** 标记破坏性变更]
+
+## Impact
+- 受影响的规范：[列出功能]
+- 受影响的代码：[关键文件/系统]
+```
+
+3. **创建规范增量：** `specs/[capability]/spec.md`
+```markdown
+## ADDED Requirements
+### Requirement: New Feature
+系统应提供...
+
+#### Scenario: Success case
+- **WHEN** 用户执行操作
+- **THEN** 预期结果
+
+## MODIFIED Requirements
+### Requirement: Existing Feature
+[完整的修改需求]
+
+## REMOVED Requirements
+### Requirement: Old Feature
+**Reason**: [为什么删除]
+**Migration**: [如何处理]
+```
+如果多个功能受到影响，在 `changes/[change-id]/specs//spec.md` 下创建多个增量文件——每个功能一个。
+
+4. **创建 tasks.md：**
+```markdown
+## 1. Implementation
+- [ ] 1.1 创建数据库模式
+- [ ] 1.2 实施 API 端点
+- [ ] 1.3 添加前端组件
+- [ ] 1.4 编写测试
+```
+
+5. **在需要时创建 design.md：**
+如果以下任何一项适用，则创建 `design.md`；否则省略：
+- 跨领域变更（多个服务/模块）或新的架构模式
+- 新的外部依赖项或重大数据模型变更
+- 安全性、性能或迁移复杂性
+- 在编码之前从技术决策中受益的模糊性
+
+最小的 `design.md` 骨架：
+```markdown
+## Context
+[背景、约束、利益相关者]
+
+## Goals / Non-Goals
+- Goals: [...]
+- Non-Goals: [...]
+
+## Decisions
+- Decision: [什么和为什么]
+- Alternatives considered: [选项 + 理由]
+
+## Risks / Trade-offs
+- [风险] → 缓解措施
+
+## Migration Plan
+[步骤、回滚]
+
+## Open Questions
+- [...]
+```
+
+## 规范文件格式
+
+### 关键：场景格式
+
+**正确**（使用 #### 标题）：
+```markdown
+#### Scenario: User login success
+- **WHEN** 提供有效凭据
+- **THEN** 返回 JWT 令牌
+```
+
+**错误**（不要使用项目符号或粗体）：
+```markdown
+- **Scenario: User login** ❌
+**Scenario**: User login ❌
+### Scenario: User login ❌
+```
+
+每个需求必须至少有一个场景。
+
+### 需求措辞
+- 对规范性需求使用 SHALL/MUST（除非有意为非规范性，否则避免使用 should/may）
+
+### 增量操作
+
+- `## ADDED Requirements` - 新功能
+- `## MODIFIED Requirements` - 更改的行为
+- `## REMOVED Requirements` - 已弃用的功能
+- `## RENAMED Requirements` - 名称更改
+
+标题使用 `trim(header)` 匹配 - 忽略空格。
+
+#### 何时使用 ADDED vs MODIFIED
+- ADDED：引入可以作为需求独立存在的新功能或子功能。当变更是正交的（例如，添加"斜杠命令配置"）而不是改变现有需求的语义时，优先使用 ADDED。
+- MODIFIED：更改现有需求的行为、范围或验收标准。始终粘贴完整的、更新的需求内容（标题 + 所有场景）。归档器将用您在此处提供的内容替换整个需求；部分增量将丢弃以前的详细信息。
+- RENAMED：仅在名称更改时使用。如果您还更改了行为，请使用 RENAMED（名称）加上引用新名称的 MODIFIED（内容）。
+
+常见陷阱：使用 MODIFIED 添加新关注点而不包括以前的文本。这会在归档时导致详细信息丢失。如果您没有明确更改现有需求，请在 ADDED 下添加新需求。
+
+正确编写 MODIFIED 需求：
+1) 在 `openspec/specs//spec.md` 中找到现有需求。
+2) 复制整个需求块（从 `### Requirement: ...` 到其场景）。
+3) 将其粘贴到 `## MODIFIED Requirements` 下并编辑以反映新行为。
+4) 确保标题文本完全匹配（不区分空格）并保留至少一个 `#### Scenario:`。
+
+RENAMED 示例：
+```markdown
+## RENAMED Requirements
+- FROM: `### Requirement: Login`
+- TO: `### Requirement: User Authentication`
+```
+
+## 故障排除
+
+### 常见错误
+
+**"Change must have at least one delta"**
+- 检查 `changes/[name]/specs/` 是否存在 .md 文件
+- 验证文件是否有操作前缀（## ADDED Requirements）
+
+**"Requirement must have at least one scenario"**
+- 检查场景是否使用 `#### Scenario:` 格式（4 个井号）
+- 不要对场景标题使用项目符号或粗体
+
+**静默场景解析失败**
+- 需要精确格式：`#### Scenario: Name`
+- 使用以下命令调试：`openspec show [change] --json --deltas-only`
+
+### 验证提示
+
+```bash
+# 始终使用严格模式进行全面检查
+openspec validate [change] --strict
+
+# 调试增量解析
+openspec show [change] --json | jq '.deltas'
+
+# 检查特定需求
+openspec show [spec] --json -r 1
+```
+
+## 快乐路径脚本
+
+```bash
+# 1) 探索当前状态
+openspec spec list --long
+openspec list
+# 可选的全文搜索：
+# rg -n "Requirement:|Scenario:" openspec/specs
+# rg -n "^#|Requirement:" openspec/changes
+
+# 2) 选择变更 id 并搭建
+CHANGE=add-two-factor-auth
+mkdir -p openspec/changes/$CHANGE/{specs/auth}
+printf "## Why\n...\n\n## What Changes\n- ...\n\n## Impact\n- ...\n" > openspec/changes/$CHANGE/proposal.md
+printf "## 1. Implementation\n- [ ] 1.1 ...\n" > openspec/changes/$CHANGE/tasks.md
+
+# 3) 添加增量（示例）
+cat > openspec/changes/$CHANGE/specs/auth/spec.md << 'EOF'
+## ADDED Requirements
+### Requirement: Two-Factor Authentication
+用户必须在登录期间提供第二因素。
+
+#### Scenario: OTP required
+- **WHEN** 提供有效凭据
+- **THEN** 需要 OTP 挑战
+EOF
+
+# 4) 验证
+openspec validate $CHANGE --strict
+```
+
+## 多功能示例
+
+```
+openspec/changes/add-2fa-notify/
+├── proposal.md
+├── tasks.md
+└── specs/
+ ├── auth/
+ │ └── spec.md # ADDED: Two-Factor Authentication
+ └── notifications/
+ └── spec.md # ADDED: OTP email notification
+```
+
+auth/spec.md
+```markdown
+## ADDED Requirements
+### Requirement: Two-Factor Authentication
+...
+```
+
+notifications/spec.md
+```markdown
+## ADDED Requirements
+### Requirement: OTP Email Notification
+...
+```
+
+## 最佳实践
+
+### 简单优先
+- 默认为 <100 行新代码
+- 单文件实现，直到证明不足
+- 避免没有明确理由的框架
+- 选择无聊的、经过验证的模式
+
+### 复杂性触发器
+仅在以下情况下添加复杂性：
+- 性能数据显示当前解决方案太慢
+- 具体的规模要求（>1000 用户，>100MB 数据）
+- 需要抽象的多个经过验证的用例
+
+### 清晰的引用
+- 使用 `file.ts:42` 格式表示代码位置
+- 将规范引用为 `specs/auth/spec.md`
+- 链接相关变更和 PR
+
+### 功能命名
+- 使用动词-名词：`user-auth`、`payment-capture`
+- 每个功能单一目的
+- 10 分钟可理解性规则
+- 如果描述需要"AND"，则拆分
+
+### 变更 ID 命名
+- 使用 kebab-case，简短且描述性：`add-two-factor-auth`
+- 优先使用动词引导的前缀：`add-`、`update-`、`remove-`、`refactor-`
+- 确保唯一性；如果已占用，追加 `-2`、`-3` 等
+
+## 工具选择指南
+
+| 任务 | 工具 | 原因 |
+|------|------|-----|
+| 按模式查找文件 | Glob | 快速模式匹配 |
+| 搜索代码内容 | Grep | 优化的正则表达式搜索 |
+| 读取特定文件 | Read | 直接文件访问 |
+| 探索未知范围 | Task | 多步骤调查 |
+
+## 错误恢复
+
+### 变更冲突
+1. 运行 `openspec list` 查看活跃的变更
+2. 检查重叠的规范
+3. 与变更所有者协调
+4. 考虑合并提案
+
+### 验证失败
+1. 使用 `--strict` 标志运行
+2. 检查 JSON 输出以获取详细信息
+3. 验证规范文件格式
+4. 确保场景格式正确
+
+### 缺少上下文
+1. 首先阅读 project.md
+2. 检查相关规范
+3. 审查最近的归档
+4. 寻求澄清
+
+## 快速参考
+
+### 阶段指示器
+- `changes/` - 提议的，尚未构建
+- `specs/` - 已构建和部署
+- `archive/` - 已完成的变更
+
+### 文件目的
+- `proposal.md` - 为什么和什么
+- `tasks.md` - 实施步骤
+- `design.md` - 技术决策
+- `spec.md` - 需求和行为
+
+### CLI 要点
+```bash
+openspec list # 正在进行什么？
+openspec show [item] # 查看详细信息
+openspec validate --strict # 是否正确？
+openspec archive [--yes|-y] # 标记完成（添加 --yes 进行自动化）
+```
+
+记住：规范是真实的。变更是提案。保持它们同步。
diff --git a/openspec/changes/add-chinese-documentation/proposal.md b/openspec/changes/add-chinese-documentation/proposal.md
new file mode 100644
index 00000000..4e98c443
--- /dev/null
+++ b/openspec/changes/add-chinese-documentation/proposal.md
@@ -0,0 +1,28 @@
+# Add Chinese Documentation
+
+## Why
+
+OpenSpec currently only provides documentation in English, which creates barriers for Chinese-speaking developers who want to adopt spec-driven development. Adding Chinese translations will:
+- Make OpenSpec accessible to the large Chinese developer community
+- Improve adoption in Chinese-speaking regions
+- Demonstrate OpenSpec's commitment to internationalization
+
+## What Changes
+
+- Add Chinese versions of all core documentation files:
+ - `README.zh-CN.md` - Main project README
+ - `AGENTS.zh-CN.md` - Root-level agent instructions
+ - `openspec/AGENTS.zh-CN.md` - OpenSpec-specific agent instructions
+ - `docs/artifact_poc.zh-CN.md` - Artifact POC documentation
+ - `docs/schema-customization.zh-CN.md` - Schema customization guide
+ - `docs/schema-workflow-gaps.zh-CN.md` - Schema workflow gaps analysis
+- Establish naming convention: `.zh-CN.md` for Chinese versions
+- Keep Chinese docs synchronized with English originals
+
+## Impact
+
+- **Affected specs**: `docs-agent-instructions` (new documentation structure)
+- **Affected code**: None - this is documentation-only
+- **Breaking changes**: None
+- **New files**: 6 new Chinese documentation files
+- **Maintenance**: Chinese docs will need updates when English docs change
diff --git a/openspec/changes/add-chinese-documentation/specs/docs-agent-instructions/spec.md b/openspec/changes/add-chinese-documentation/specs/docs-agent-instructions/spec.md
new file mode 100644
index 00000000..f61dbf08
--- /dev/null
+++ b/openspec/changes/add-chinese-documentation/specs/docs-agent-instructions/spec.md
@@ -0,0 +1,22 @@
+# docs-agent-instructions Specification Delta
+
+## ADDED Requirements
+
+### Requirement: Chinese Documentation Support
+The documentation system SHALL provide Chinese translations of all core documentation files to support Chinese-speaking developers.
+
+#### Scenario: Chinese version availability
+- **WHEN** a developer accesses any core documentation file
+- **THEN** a Chinese version SHALL be available with the naming convention `.zh-CN.md`
+- **AND** the English version SHALL include a link to the Chinese version at the top
+
+#### Scenario: Translation consistency
+- **WHEN** Chinese documentation is created or updated
+- **THEN** all technical terms, code examples, and CLI commands SHALL remain in English
+- **AND** the translation SHALL maintain the same structure and formatting as the English version
+- **AND** all links and references SHALL point to the correct locations
+
+#### Scenario: Documentation synchronization
+- **WHEN** English documentation is updated
+- **THEN** the corresponding Chinese documentation SHOULD be updated to maintain consistency
+- **AND** version indicators or timestamps MAY be used to track translation currency
diff --git a/openspec/changes/add-chinese-documentation/tasks.md b/openspec/changes/add-chinese-documentation/tasks.md
new file mode 100644
index 00000000..99a4bcb5
--- /dev/null
+++ b/openspec/changes/add-chinese-documentation/tasks.md
@@ -0,0 +1,39 @@
+# Implementation Tasks
+
+## 1. Create Chinese Documentation Files
+- [ ] 1.1 Translate `README.md` to `README.zh-CN.md`
+ - Translate project overview, installation instructions, and usage examples
+ - Maintain all code examples and command syntax unchanged
+ - Preserve markdown formatting and links
+- [ ] 1.2 Translate `AGENTS.md` to `AGENTS.zh-CN.md`
+ - Translate root-level agent instructions
+ - Keep all technical terms and file paths in English
+ - Maintain code block formatting
+- [ ] 1.3 Translate `openspec/AGENTS.md` to `openspec/AGENTS.zh-CN.md`
+ - Translate OpenSpec-specific workflow instructions
+ - Preserve all CLI commands and examples
+ - Keep directory structure examples unchanged
+- [ ] 1.4 Translate `docs/artifact_poc.md` to `docs/artifact_poc.zh-CN.md`
+ - Translate artifact POC documentation
+ - Maintain technical accuracy
+- [ ] 1.5 Translate `docs/schema-customization.md` to `docs/schema-customization.zh-CN.md`
+ - Translate schema customization guide
+ - Keep YAML examples and code unchanged
+- [ ] 1.6 Translate `docs/schema-workflow-gaps.md` to `docs/schema-workflow-gaps.zh-CN.md`
+ - Translate workflow gaps analysis
+ - Preserve technical terminology
+
+## 2. Quality Assurance
+- [ ] 2.1 Review all translations for accuracy and consistency
+ - Verify technical terms are correctly translated
+ - Ensure code examples remain functional
+ - Check that links point to correct locations
+- [ ] 2.2 Validate markdown formatting
+ - Ensure all headers, lists, and code blocks render correctly
+ - Verify links work properly
+ - Check that tables and diagrams display correctly
+
+## 3. Documentation
+- [ ] 3.1 Add note to English docs about Chinese versions
+ - Add link to Chinese version at top of each English doc
+ - Use format: "中文版本 | [Chinese Version](filename.zh-CN.md)"