openspec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenSpec (OPSX) Skill

OpenSpec (OPSX) 技能

Use this skill to guide or reason about the OpenSpec artifact-driven workflow system (OPSX), including artifact graphs, schema/template resolution, change lifecycle, and experimental commands/skills.

使用此技能来指导或推理OpenSpec工件驱动工作流系统（OPSX），包括工件图谱、模式/模板解析、变更生命周期以及实验性命令/技能。

When to Use

使用场景

You need to explain or apply the artifact-driven workflow (OPSX).
You are planning or reviewing changes based on artifact dependencies.
You need to interpret schema/template resolution rules (XDG + built-ins).
You are asked to design or validate changes to the OpenSpec workflow or schema tooling.
You are asked to create or operate OpenSpec experimental skills/commands.

你需要解释或应用工件驱动工作流（OPSX）。
你正基于工件依赖规划或评审变更。
你需要解读模式/模板解析规则（XDG + 内置规则）。
你被要求设计或验证对OpenSpec工作流或模式工具的变更。
你被要求创建或操作OpenSpec实验性技能/命令。

Quick Navigation

快速导航

Artifact graph core concepts: references/artifact-core.md
OPSX workflow behavior and usage: references/opsx-workflow.md
Setup + profiles (init, update, config profile): references/setup-profiles.md
Schema customization workflow and gaps: references/schema-customization.md
End-to-end schema workflow gaps and proposed solution: references/schema-workflow-gaps.md
Experimental release plan and rollout checklist: references/experimental-release-plan.md

工件图谱核心概念：references/artifact-core.md
OPSX工作流行为与用法：references/opsx-workflow.md
设置 + 配置文件（初始化、更新、配置文件）：references/setup-profiles.md
模式自定义工作流与不足：references/schema-customization.md
端到端模式工作流不足与提议解决方案：references/schema-workflow-gaps.md
实验版本发布计划与推出清单：references/experimental-release-plan.md

Release Highlights (1.1.1 → 1.2.0)

版本更新亮点（1.1.1 → 1.2.0）

Profiles: select a workflow profile via
```
openspec config profile
```
(preset:
```
core
```
or custom selection) and apply it to a project via
```
openspec update
```
.
Propose workflow (all-at-once): legacy slash command
```
/openspec:proposal
```
creates proposal + specs + design + tasks in one request (instead of
```
/opsx:new
```
+
```
/opsx:ff
```
).
More tool integrations: adds support for Pi and Kiro tool directories.
Cleaner updates:
```
openspec update
```
can prune deselected workflows to keep projects tidy.

配置文件：通过
```
openspec config profile
```
选择工作流配置文件（预设：
```
core
```
或自定义选择），并通过
```
openspec update
```
应用到项目中。
一键提议工作流：旧版斜杠命令
```
/openspec:proposal
```
可在一次请求中创建提议+规格+设计+任务（替代
```
/opsx:new
```
+
```
/opsx:ff
```
）。
更多工具集成：新增对Pi和Kiro工具目录的支持。
更简洁的更新：
```
openspec update
```
可清理未选中的工作流，保持项目整洁。

OPSX Commands

OPSX 命令

Command	Purpose
`/opsx:explore`	Think through ideas, investigate problems (no structure)
`/opsx:new`	Start a new change
`/opsx:continue`	Create next artifact based on dependencies
`/opsx:ff`	Fast-forward — create all planning artifacts at once
`/opsx:apply`	Implement tasks, updating artifacts as needed
`/opsx:verify`	Validate implementation matches spec
`/opsx:sync`	Sync delta specs to main specs
`/opsx:archive`	Archive single completed change
`/opsx:bulk-archive`	Archive multiple completed changes at once

Legacy (non-OPSX) command:

/openspec:proposal

creates all planning artifacts at once. Prefer OPSX, but this can be useful for small/straightforward changes or older setups.

命令	用途
`/opsx:explore`	构思想法、排查问题（无固定结构）
`/opsx:new`	启动新变更
`/opsx:continue`	基于依赖创建下一个工件
`/opsx:ff`	快速推进 — 一次性创建所有规划工件
`/opsx:apply`	执行任务，按需更新工件
`/opsx:verify`	验证实现是否符合规格
`/opsx:sync`	将增量规格同步到主规格
`/opsx:archive`	归档单个已完成的变更
`/opsx:bulk-archive`	一次性归档多个已完成的变更

旧版（非OPSX）命令：

/openspec:proposal

可一次性创建所有规划工件。优先使用OPSX，但此命令在小型/简单变更或旧版设置中仍有用处。

Schema Management

模式管理

bash

openspec schemas                    # List available schemas
openspec schema which --all         # Show resolution sources
openspec schema init my-workflow    # Create new schema interactively
openspec schema fork spec-driven my-workflow  # Fork existing schema
openspec schema validate my-workflow  # Validate schema structure

bash

openspec schemas                    # 列出可用模式
openspec schema which --all         # 显示解析来源
openspec schema init my-workflow    # 交互式创建新模式
openspec schema fork spec-driven my-workflow  # 复刻现有模式
openspec schema validate my-workflow  # 验证模式结构

Project Configuration

项目配置

Create

openspec/config.yaml

for per-project settings:

yaml

schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  Testing: Vitest, Playwright

rules:
  proposal:
    - Include rollback plan
  specs:
    - Use Given/When/Then format

Schema precedence: CLI flag → Change metadata → Project config → Default (

spec-driven

)

创建

openspec/config.yaml

用于项目级设置：

yaml

schema: spec-driven

context: |
  技术栈：TypeScript, React, Node.js
  测试：Vitest, Playwright

rules:
  proposal:
    - 包含回滚计划
  specs:
    - 使用Given/When/Then格式

模式优先级：CLI标志 → 变更元数据 → 项目配置 → 默认值（

spec-driven

）

Core Concepts

核心概念

Artifact graph, not a workflow engine: Dependencies enable actions; they do not force linear phases.
Filesystem-as-database: Completion is derived from file existence, not stored state.
Deterministic CLI: Commands require explicit change context (agent infers, CLI remains strict).
XDG schema resolution: User overrides take precedence over built-ins.
Templates are schema-scoped: Templates live next to schema and resolve with a strict 2-level fallback.

工件图谱，而非工作流引擎：依赖关系启用操作；不强制线性阶段。
文件系统即数据库：完成状态由文件存在性推导，而非存储的状态。
确定性CLI：命令需要明确的变更上下文（Agent可推断，CLI保持严格）。
XDG模式解析：用户覆盖优先级高于内置规则。
模板与模式绑定：模板与模式共存，并通过严格的两级回退机制解析。

Decision Rules

决策规则

Prefer update when intent stays the same and you are refining scope or approach.
Prefer new change when intent or scope fundamentally shifts, or the original can be completed independently.
Always preserve a clear history of why artifacts changed (proposal/specs/design/tasks).

当意图不变且你正在细化范围或方法时，优先选择更新。
当意图或范围发生根本性变化，或原变更可独立完成时，优先选择新建变更。
始终保留工件变更原因的清晰历史记录（提议/规格/设计/任务）。

Recipes

操作指南

1) Show what is ready to create next

1) 显示可创建的下一个工件

Determine the active change id.
Query status and ready artifacts with the change explicitly set.
Present ready artifacts and their dependencies.

Expected behavior: show ready artifacts, not required steps.

确定活动变更ID。
显式设置变更后查询状态和可创建的工件。
展示可创建的工件及其依赖项。

预期行为：显示可创建的工件，而非必填步骤。

2) Generate instructions for a specific artifact

2) 生成特定工件的说明

Resolve schema and template with XDG fallback.
Build context: change metadata, dependency status, and target paths.
Return enriched instructions in plain Markdown.

通过XDG回退机制解析模式和模板。
构建上下文：变更元数据、依赖状态和目标路径。
返回富文本格式的Markdown说明。

3) Start a new change

3) 启动新变更

Validate change name (kebab-case).
Create change directory and README.
Show initial status and first ready artifact.

验证变更名称（kebab-case格式）。
创建变更目录和README。
显示初始状态和第一个可创建的工件。

4) Schema customization guidance

4) 模式自定义指南

Explain XDG override paths.
Describe copying built-in schema + templates.
Provide verification steps or recommended CLI commands for listing and resolving.

解释XDG覆盖路径。
描述复制内置模式+模板的方法。
提供用于列出和解析的验证步骤或推荐CLI命令。

5) Explain schema binding for a change

5) 解释变更的模式绑定

Prefer change metadata if available.
Fallback to project default schema if configured.
Otherwise default to spec-driven.

优先使用变更元数据（如果可用）。
回退到项目默认模式（如果已配置）。
否则默认使用spec-driven。

Prohibitions

禁止操作

Do not treat the system as a linear workflow engine.
Do not assume a change is active without explicit selection.
Do not silently fall back between schemas or templates without reporting.
Do not copy long vendor docs verbatim; summarize and provide actionable guidance.

不要将系统视为线性工作流引擎。
不要在未显式选择的情况下假设存在活动变更。
不要在未告知用户的情况下在模式或模板之间静默回退。
不要直接复制冗长的供应商文档；应总结并提供可操作的指导。

Output Expectations

输出预期

Give clear artifact readiness and dependency explanations.
Use explicit change identifiers in examples.
Provide concise, actionable steps and indicate whether they are informational or required.

提供清晰的工件就绪状态和依赖关系说明。
在示例中使用明确的变更标识符。
提供简洁、可操作的步骤，并指明这些步骤是信息性的还是必填的。