openspec

OpenSpec（OPSX）技能

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

快速导航

• 产物图核心概念：references/artifact-core.md
• OPSX 工作流行为和用法：references/opsx-workflow.md
• 设置 + 配置档（init、update、config profile）：references/setup-profiles.md
• schema 自定义工作流和差距：references/schema-customization.md
• 端到端 schema 工作流差距和提议的解决方案：references/schema-workflow-gaps.md
• 实验版发布计划和推出检查清单：references/experimental-release-plan.md

发布亮点（1.2.0 → 1.3.0）

• **更多工具集成：**新增对 Junie、Lingma、ForgeCode 和 IBM Bob 的支持。
• **更安全的设置：**现在默认不安装 shell 补全，且仅有一个空的 .github/ 目录不再触发 Copilot 自动检测。
• **适配器修复：**修正了 Pi 命令生成，且 OpenCode 现在使用规范的 .opencode/commands/ 路径。
• **更安全的状态检查：**当项目尚无变更时，openspec status 现在会正常退出。

OPSX 命令

命令	用途
/opsx:explore	梳理想法、调查问题（无结构）
/opsx:new	开始一项新变更
/opsx:continue	根据依赖关系创建下一个产物
/opsx:ff	快进——一次性创建所有规划产物
/opsx:apply	实施任务，并按需更新产物
/opsx:verify	验证实现是否符合规格
/opsx:sync	将增量规格同步到主规格
/opsx:archive	归档一项已完成的变更
/opsx:bulk-archive	一次性归档多项已完成的变更

旧版（非 OPSX）命令：/openspec:proposal 一次性创建所有规划产物。建议优先使用 OPSX，但对于小型/简单的变更或较旧的设置，此命令可能很有用。

Schema 管理

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

项目配置

创建 openspec/config.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 优先级：**CLI 标志 → 变更元数据 → 项目配置 → 默认值（spec-driven）

核心概念

• 产物图，而非工作流引擎：依赖关系用于启用操作，不会强制执行线性阶段。
• 文件系统即数据库：根据文件是否存在来判断完成状态，而非存储状态。
• 确定性 CLI：命令要求显式指定变更上下文（Agent 会推断，CLI 则保持严格）。
• XDG schema 解析：用户覆盖项优先于内置项。
• 模板按 schema 划分范围：模板与 schema 存放在一起，并通过严格的两级回退机制解析。

决策规则

• 当意图保持不变，只是在细化范围或方法时，优先选择更新。
• 当意图或范围发生根本变化，或原始变更可以独立完成时，优先选择新建变更。
• 始终清晰保留产物（提案/规格/设计/任务）变更原因的历史记录。

操作示例

1）查看接下来可以创建的内容

1. 确定当前变更 ID。
2. 明确指定变更，查询状态和就绪的产物。
3. 展示就绪的产物及其依赖关系。

预期行为：展示就绪的产物，而不是必需步骤。

2）为特定产物生成指令

1. 使用 XDG 回退机制解析 schema 和模板。
2. 构建上下文：变更元数据、依赖状态和目标路径。
3. 以纯 Markdown 返回补充完善的指令。

3）开始一项新变更

1. 验证变更名称（kebab-case）。
2. 创建变更目录和 README。
3. 显示初始状态和第一个就绪的产物。

4）架构自定义指南

1. 说明 XDG 覆盖路径。
2. 描述如何复制内置架构和模板。
3. 提供验证步骤或建议使用的 CLI 命令，以列出和解析内容。

5）说明变更的架构绑定

1. 如果有变更元数据，优先使用。
2. 如果已配置项目默认架构，则回退使用该架构。
3. 否则，默认采用规范驱动模式。

禁止事项

• 不要将系统视为线性工作流引擎。
• 未经明确选择，不要假设某项变更处于活动状态。
• 在架构或模板之间静默回退，而不进行说明。
• 不要逐字复制大段供应商文档；请提供摘要和可操作的指导。

输出要求

• 清楚说明产物的就绪状态及其依赖关系。
• 在示例中明确使用变更标识符。
• 提供简洁、可操作的步骤，并说明哪些是说明性内容、哪些是必需步骤。

链接

• 文档
• 版本发布
• GitHub
• npm