openspec-schema

用途

OpenSpec Schema 技能用于通过 openspec schema 子命令创建和管理自定义工作流 schema。Schema 定义了工作流中存在哪些产物（artifacts）以及它们之间的依赖关系。默认的 spec-driven schema 提供 proposal -> specs -> design -> tasks 的流程，但自定义 schema 允许定义不同的工作流。

何时使用

用户想要自定义工作流（例如研究优先、快速迭代）。
用户说“创建 schema”“自定义工作流”“分叉 spec-driven schema”。
调试 schema 解析（openspec schema which）。
验证自定义 schema 的结构。

前置条件

已安装 OpenSpec CLI（参见 openspec-install）。

使用方式

从零创建新 schema

openspec schema init my-workflow
# 交互式：提示输入描述、产物、默认值
# 非交互式：
openspec schema init rapid --description "Rapid iteration" --artifacts "proposal,tasks" --default

创建 openspec/schemas/my-workflow/ 目录，包含 schema.yaml 和 templates/。

分叉现有 schema

openspec schema fork spec-driven my-workflow

复制 spec-driven schema 以便自定义。

验证 schema

openspec schema validate my-workflow
# 或验证全部：
openspec schema validate

检查 schema 解析

openspec schema which spec-driven
# 显示：package、project 或 user 来源
openspec schema which --all

Schema 结构

openspec/schemas/<name>/
├── schema.yaml       # 产物定义与依赖关系
└── templates/
    ├── proposal.md   # 每个产物的模板
    ├── specs.md
    ├── design.md
    └── tasks.md

schema.yaml 示例

name: research-first
artifacts:
  - id: research
    generates: research.md
    requires: []
  - id: proposal
    generates: proposal.md
    requires: [research]
  - id: tasks
    generates: tasks.md
    requires: [proposal]

Schema 优先级

Project：openspec/schemas/<name>/（本地，纳入版本控制）
User：~/.local/share/openspec/schemas/<name>/（全局）
Package：内置 schema（例如 spec-driven）

输出

在 openspec/schemas/<name>/ 中生成包含 schema.yaml 和 templates 的自定义 schema。

后续步骤

配合 openspec-new 使用该 schema：/opsx:new my-change --schema my-workflow。
或在 openspec-config（openspec/config.yaml）中设为默认。

故障排查

“Schema not found”：检查 openspec schemas 查看可用 schema；检查 openspec schema which <name> 查看解析来源。
验证错误：运行 openspec schema validate <name> --verbose 查看详情。
规则中出现未知产物 ID：检查 openspec schemas --json 查看每个 schema 的产物 ID。

参考

OpenSpec CLI：schema 命令
OpenSpec Concepts：Schemas
OpenSpec Customization