openspec-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenSpec Workflow

OpenSpec 工作流

Use OpenSpec as the spec/change control plane for non-trivial changes to this repository's portable agent assets, downstream tooling, docs generation, hooks, bundle metadata, or validation behavior.

将OpenSpec用作本仓库中可移植Agent资产、下游工具、文档生成、钩子、包元数据或验证行为的非微小变更的规范/变更控制平面。

Dispatch

调度

`$ARGUMENTS`	Action
Empty	Show the repo OpenSpec quick path
`doctor`	Diagnose OpenSpec toolchain and project state
`init [tools]`	Materialize downstream OpenSpec skills/commands locally
`status <change>`	Read change artifact status as JSON
`instructions <artifact> <change>`	Get AI-readable next-step instructions
`validate`	Validate all OpenSpec specs and changes
`archive <change>`	Validate and archive a completed change
Natural language change request	Decide whether OpenSpec is warranted, then create or continue a change

`$ARGUMENTS`	操作
空值	显示仓库OpenSpec快速路径
`doctor`	诊断OpenSpec工具链和项目状态
`init [tools]`	在本地实例化下游OpenSpec技能/命令
`status <change>`	以JSON格式读取变更工件状态
`instructions <artifact> <change>`	获取AI可读的下一步指令
`validate`	验证所有OpenSpec规范和变更
`archive <change>`	验证并归档已完成的变更
自然语言变更请求	判断是否需要使用OpenSpec，然后创建或继续变更流程

Quick Path

快速路径

Diagnose setup before OpenSpec work:

bash

uv run python skills/openspec-workflow/scripts/openspec_cli.py doctor

For non-trivial repo changes, create or continue an OpenSpec change using the generated upstream OpenSpec skills/commands when available.
When generated upstream OpenSpec skills are not available, use repo wrappers for structured state:

bash

uv run python skills/openspec-workflow/scripts/openspec_cli.py status --change <change> --format json
uv run python skills/openspec-workflow/scripts/openspec_cli.py instructions <artifact> --change <change> --format json

Validate before implementation completion or archive:

bash

uv run python skills/openspec-workflow/scripts/openspec_cli.py validate

在开展OpenSpec工作前诊断环境设置：

bash

uv run python skills/openspec-workflow/scripts/openspec_cli.py doctor

对于非微小仓库变更，若上游已生成OpenSpec技能/命令，使用它们来创建或继续OpenSpec变更。
若上游未生成OpenSpec技能，使用仓库包装器来获取结构化状态：

bash

uv run python skills/openspec-workflow/scripts/openspec_cli.py status --change <change> --format json
uv run python skills/openspec-workflow/scripts/openspec_cli.py instructions <artifact> --change <change> --format json

在完成实现或归档前进行验证：

bash

uv run python skills/openspec-workflow/scripts/openspec_cli.py validate

When To Use OpenSpec

何时使用OpenSpec

Use OpenSpec when the change affects any of these surfaces:

```
skills/
```
,
```
agents/
```
,
```
mcp/
```
,
```
mcp.json
```
, or first-party MCP conventions
```
AGENTS.md
```
,
```
instructions/
```
, or platform bridge files
```
agent-bundle.json
```
, plugin manifests, sync manifests, or downstream harness setup
portable skill CLI behavior, generated README/docs output, or docs navigation
OpenSpec specs, schemas, or generated downstream tool setup

Skip OpenSpec for small, isolated typo fixes or single-file local changes where the user's request and repo conventions fully determine the outcome.

When a non-trivial change has user-pivotal scope or approach forks, apply

instructions/global.md

Depth routing and invoke

/grill-me

before creating or continuing change artifacts.

当变更影响以下任何层面时，使用OpenSpec：

```
skills/
```
,
```
agents/
```
,
```
mcp/
```
,
```
mcp.json
```
, 或第一方MCP约定
```
AGENTS.md
```
,
```
instructions/
```
, 或平台桥接文件
```
agent-bundle.json
```
, 插件清单, 同步清单, 或下游 harness 设置
可移植技能CLI行为, 生成的README/文档输出, 或文档导航
OpenSpec规范, 模式, 或生成的下游工具设置

若为小型孤立的拼写错误修复或单文件本地变更，且用户需求与仓库约定完全决定结果，则无需使用OpenSpec。

当非微小变更涉及用户关键范围或方案分支时，应用

instructions/global.md

深度路由，并在创建或继续变更工件前调用

/grill-me

。

Downstream Tooling

下游工具

OpenSpec-generated upstream skills and commands are local/generated by default. Materialize them when a downstream tool should expose native OpenSpec workflows:

bash

uv run python skills/openspec-workflow/scripts/openspec_cli.py init --apply
uv run python skills/openspec-workflow/scripts/openspec_cli.py update --apply

The default repo mapping is:

Repo agent	OpenSpec tool
`claude-code`	`claude`
`codex`	`codex`
`crush`	`crush`
`cursor`	`cursor`
`opencode`	`opencode`

Do not commit generated

.claude

.cursor

.opencode

.agent

.crush

, or

.codex

OpenSpec artifacts unless the user explicitly promotes a specific artifact to repo-owned source.

OpenSpec生成的上游技能和命令默认是本地/生成的。当下游工具需要暴露原生OpenSpec工作流时，将其实例化：

bash

uv run python skills/openspec-workflow/scripts/openspec_cli.py init --apply
uv run python skills/openspec-workflow/scripts/openspec_cli.py update --apply

默认仓库映射如下：

仓库Agent	OpenSpec工具
`claude-code`	`claude`
`codex`	`codex`
`crush`	`crush`
`cursor`	`cursor`
`opencode`	`opencode`

除非用户明确将特定工件提升为仓库所有的源文件，否则请勿提交生成的

.claude

.cursor

.opencode

.agent

.crush

, 或

.codex

OpenSpec工件。

Artifact Order

工件顺序

Agent Asset Changes

Agent资产变更

For this repo's custom

agent-asset-change

schema, create artifacts in this order:

```
proposal
```
```
affected-surfaces
```
```
design
```
```
validation-matrix
```
```
tasks
```

Use

openspec status --json

to confirm which artifact is ready before asking the AI to create it.

对于本仓库自定义的

agent-asset-change

模式，按以下顺序创建工件：

```
proposal
```
（提案）
```
affected-surfaces
```
（受影响层面）
```
design
```
（设计）
```
validation-matrix
```
（验证矩阵）
```
tasks
```
（任务）

在请求AI创建工件前，使用

openspec status --json

确认哪个工件已准备就绪。

Archive Readiness

归档就绪条件

Archive only after implementation and validation are complete. Keep proposal, affected surfaces, design, validation matrix, and tasks aligned with the final shipped state.

仅在实现和验证完成后进行归档。确保提案、受影响层面、设计、验证矩阵和任务与最终发布状态保持一致。

Canonical Vocabulary

标准词汇

Use these canonical terms exactly:

Term	Meaning
OpenSpec change	A proposed repo behavior or asset change tracked under `openspec/changes/`
Artifact	A proposal, design, task list, spec delta, or AI-readable instruction document
Downstream tool setup	Generated local skills, commands, or config for external agent harnesses
Archive	Finalize and move a completed change into the durable spec history
Validation matrix	The artifact that maps affected surfaces to required proof commands

严格使用以下标准术语：

术语	含义
OpenSpec change	存储在 `openspec/changes/` 下的仓库行为或资产变更提案
Artifact	提案、设计、任务列表、规范增量或AI可读指令文档
Downstream tool setup	为外部Agent harness生成的本地技能、命令或配置
Archive	完成变更并将其移入持久规范历史中
Validation matrix	将受影响层面映射到所需验证命令的工件

Validation Contract

验证契约

Run from this skill directory before declaring changes complete:

bash

python scripts/check.py
uv run python skills/openspec-workflow/scripts/openspec_cli.py doctor --format json
uv run python skills/openspec-workflow/scripts/openspec_cli.py validate --format json

If a command is blocked by missing Node/OpenSpec tooling, report the blocker and the exact command that should be run after installing Node

>=20.19.0

Completion criteria:

```
scripts/check.py
```
exits 0.
```
openspec_cli.py doctor
```
and
```
validate
```
pass, or blockers include exact follow-up commands.
Skill directory stays free of repo control-plane CLI references.
The OpenSpec decision is grounded in repo policy and the actual affected files.
Required artifacts exist or are explicitly skipped with a reason.
Generated downstream artifacts are not committed unless explicitly promoted.

在宣布变更完成前，从本技能目录运行以下命令：

bash

python scripts/check.py
uv run python skills/openspec-workflow/scripts/openspec_cli.py doctor --format json
uv run python skills/openspec-workflow/scripts/openspec_cli.py validate --format json

若命令因缺少Node/OpenSpec工具而受阻，报告阻塞问题以及安装Node

>=20.19.0

后应运行的确切命令。

完成标准：

```
scripts/check.py
```
以0状态退出。
```
openspec_cli.py doctor
```
和
```
validate
```
通过，或阻塞问题包含确切的后续命令。
技能目录中无仓库控制平面CLI引用。
OpenSpec决策基于仓库策略和实际受影响文件。
所需工件已存在，或已明确说明跳过理由。
生成的下游工件除非明确提升，否则不提交。

Critical Rules

关键规则

Use OpenSpec for non-trivial changes to public asset formats, downstream tooling, docs generation, hooks, bundle metadata, or validation behavior.
Do not use OpenSpec for isolated typo fixes or single-file local edits where repo conventions fully determine the outcome.
Prefer
```
uv run python scripts/openspec_cli.py ... --format json
```
when another AI tool needs machine-readable state or instructions.
Do not commit generated
```
.claude
```
,
```
.cursor
```
,
```
.opencode
```
,
```
.github
```
,
```
.agent
```
,
```
.crush
```
,
```
.codex
```
, or
```
.gemini
```
OpenSpec artifacts unless explicitly promoted.
Validate before archive; never archive a change that has unresolved task, spec, or validation gaps.
Keep downstream generated skills and commands local by default.
Report missing OpenSpec or Node tooling as blockers with the exact command to retry after setup.

对公共资产格式、下游工具、文档生成、钩子、包元数据或验证行为的非微小变更使用OpenSpec。
对于孤立拼写错误修复或单文件本地编辑（仓库约定完全决定结果），请勿使用OpenSpec。
当其他AI工具需要机器可读状态或指令时，优先使用
```
uv run python scripts/openspec_cli.py ... --format json
```
。
除非明确提升，否则请勿提交生成的
```
.claude
```
,
```
.cursor
```
,
```
.opencode
```
,
```
.github
```
,
```
.agent
```
,
```
.crush
```
,
```
.codex
```
, 或
```
.gemini
```
OpenSpec工件。
归档前先验证；绝不要归档存在未解决任务、规范或验证缺口的变更。
默认将下游生成的技能和命令保留在本地。
将缺少OpenSpec或Node工具的情况作为阻塞问题报告，并提供设置完成后重试的确切命令。