superspec-research

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Superspec Research

Superspec 研究

Rules (non-negotiable)

规则（不可协商）

Drive OpenSpec via CLI only (NO OpenSpec slash commands; i.e., commands starting with
```
/opsx
```
or
```
/openspec
```
).
Prefer JSON output for every OpenSpec call that supports it (use
```
--json
```
).
- If a required command does not support
```
--json
```
  (e.g.,
```
openspec new change
```
  ), run it without
```
--json
```
  and continue with the next JSON-capable command (typically
```
openspec status --change <change> --json
```
  ).
Keep changes scoped to
```
proposal
```
and
```
specs
```
artifacts only.
If
```
proposal
```
is not complete, run the brainstorming prelude before writing
```
proposal.md
```
(see
```
skills/superspec-brainstorm/SKILL.md
```
).

仅通过CLI驱动OpenSpec（禁止使用OpenSpec斜杠命令；即，以
```
/opsx
```
或
```
/openspec
```
开头的命令）。
对于每个支持JSON输出的OpenSpec调用，优先使用JSON格式（添加
```
--json
```
参数）。
- 如果某个必需命令不支持
```
--json
```
  （例如
```
openspec new change
```
  ），则不添加该参数运行命令，然后继续执行下一个支持JSON的命令（通常是
```
openspec status --change <change> --json
```
  ）。
变更范围仅限
```
proposal
```
和
```
specs
```
制品。
如果
```
proposal
```
未完成，在编写
```
proposal.md
```
之前先执行头脑风暴前置步骤（详见
```
skills/superspec-brainstorm/SKILL.md
```
）。

Change Selection

变更选择

If the user provides a change name, use it as
```
<change>
```
.
Else run:
- ```
openspec list --json
```
  Ask the user to confirm/select a change name from the JSON output.
If there are no changes (or user wants a new one), ask for:
- change name (kebab-case)
- one-sentence description Then run:
- ```
openspec new change <change> --schema superspec-rpi --description "<description>"
```

Always print:

```
Selected change: <change>
```

如果用户提供了变更名称，将其作为
```
<change>
```
使用。
否则运行：
- ```
openspec list --json
```
  请用户从JSON输出中确认/选择一个变更名称。
如果没有任何变更（或用户需要新建），请用户提供：
- 变更名称（短横线分隔格式，kebab-case）
- 一句话描述然后运行：
- ```
openspec new change <change> --schema superspec-rpi --description "<description>"
```

始终打印：

```
Selected change: <change>
```

Artifact Loop (proposal + specs)

制品循环（提案 + 规格）

Repeat until BOTH

proposal

and

specs

are complete.

重复执行，直到

proposal

和

specs

均完成为止。

0. Inspect status

0. 检查状态

Run:

openspec status --change <change> --json

Parse the JSON to determine, for artifacts

proposal

and

specs

whether each is
```
ready
```
vs
```
complete
```
whether
```
specs
```
is blocked by missing
```
proposal
```

If the JSON schema is unclear, show the JSON and ask the user what the status fields mean; do not guess.

运行：

openspec status --change <change> --json

解析JSON以确定

proposal

和

specs

这两个制品的：

各自处于
```
ready
```
还是
```
complete
```
状态
```
specs
```
是否因缺少
```
proposal
```
而被阻塞

如果JSON架构不明确，显示JSON内容并询问用户状态字段的含义；请勿猜测。

1. Blocked behavior

1. 阻塞处理

specs

is blocked by missing

proposal

, create

proposal

first (even if

specs

looks ready).

如果

specs

因缺少

proposal

而被阻塞，先创建

proposal

（即使

specs

显示为ready）。

1.5 Brainstorming prelude (proposal inputs)

1.5 头脑风暴前置步骤（提案输入）

proposal

is ready (and not complete), do a short clarification pass BEFORE writing files:

Follow
```
skills/superspec-brainstorm/SKILL.md
```
as a subroutine.
Do NOT run
```
openspec
```
during brainstorming.
Do NOT write or modify any files during brainstorming.
Keep a "Brainstorming Notes" block as working notes.

Exit brainstorming when:

You have concrete bullets for intent, background, in-scope, out-of-scope, constraints, affected specs, and success criteria.
Affected Specs names are decided (kebab-case), because they drive
```
specs/<kebab-name>/spec.md
```
.

Then proceed to create/update

proposal.md

using OpenSpec instructions, using the notes to fill the template precisely.

If you believe you already know all the answers, you still MUST produce the "Brainstorming Notes" block before writing

proposal.md

如果

proposal

处于ready状态（但未完成），在编写文件前先进行简短的澄清环节：

按照
```
skills/superspec-brainstorm/SKILL.md
```
中的要求执行子流程。
头脑风暴期间禁止运行
```
openspec
```
命令。
头脑风暴期间禁止编写或修改任何文件。
保留“头脑风暴笔记”块作为工作记录。

当满足以下条件时结束头脑风暴：

已明确意向、背景、范围内内容、范围外内容、约束条件、受影响规格和成功标准的具体要点。
已确定受影响规格的名称（短横线分隔格式，kebab-case），因为这些名称将决定
```
specs/<kebab-name>/spec.md
```
的路径。

然后根据OpenSpec的说明创建/更新

proposal.md

，使用笔记内容精准填充模板。

即使你认为已掌握所有信息，在编写

proposal.md

之前仍必须生成“头脑风暴笔记”块。

2. Create/Update proposal

2. 创建/更新提案

proposal

is ready (and not complete):

Run:

openspec instructions proposal --change <change> --json

From the JSON, extract at minimum:
- ```
outputPath
```
  (where to write)
- ```
template
```
  and/or
```
instruction
```
  content
Write the proposal content to the concrete
```
outputPath
```
(typically
```
proposal.md
```
).

outputPath

is not a concrete file path (unexpected), STOP and show the full JSON.

Proposal must be concise and must include a filled "Affected Specs" section (it drives specs file creation).

After writing, print:

```
Wrote proposal: <outputPath>
```

如果

proposal

处于ready状态（但未完成）：

运行：

openspec instructions proposal --change <change> --json

从JSON中至少提取：
- ```
outputPath
```
  （文件写入路径）
- ```
template
```
  和/或
```
instruction
```
  内容
将提案内容写入指定的具体路径（通常为
```
proposal.md
```
）。

如果

outputPath

不是具体的文件路径（意外情况），停止操作并显示完整的JSON内容。

提案必须简洁，且必须包含已填写的“受影响规格”部分（该部分将驱动规格文件的创建）。

编写完成后，打印：

```
Wrote proposal: <outputPath>
```

3. Create/Update specs

3. 创建/更新规格

specs

is ready (and not complete):

Run:

openspec instructions specs --change <change> --json

Read dependencies from the JSON (e.g.,
```
requires
```
) and ensure proposal exists; if not, go create proposal.
Treat
```
outputPath
```
patterns like
```
specs/**/spec.md
```
as a hint ONLY. Do not write wildcard paths.
Determine concrete spec files from the proposal "Affected Specs".

Create one delta spec per affected capability (new/modified/removed), at:

```
specs/<kebab-name>/spec.md
```

Each delta spec MUST:

Be a delta (changes only), structured into:

```
## ADDED Requirements
```
```
## MODIFIED Requirements
```
```
## REMOVED Requirements
```

Use normative language per requirement (MUST/SHALL).
For every ADDED/MODIFIED/REMOVED requirement, include Given/When/Then scenarios:
- at least one happy path (if applicable)
- at least one edge/failure case
- every
```
#### Scenario:
```
  MUST include a
```
##### Test Obligation
```
  block with:
```
Type
```
  (unit|integration|e2e),
```
Test File
```
  ,
```
Test Name
```
  ,
```
Verify Command
```
  ,
```
Expected (RED)
```
  , and
```
Key Assertions
```
  . If any field is missing, ask the user; do not guess.

After writing, print:

```
Wrote specs: <path1>[, <path2> ...]
```

如果

specs

处于ready状态（但未完成）：

运行：

openspec instructions specs --change <change> --json

从JSON中读取依赖关系（例如
```
requires
```
），确保提案已存在；如果不存在，先创建提案。
将
```
outputPath
```
模式（如
```
specs/**/spec.md
```
）仅视为提示信息。请勿写入通配符路径。
根据提案中的“受影响规格”确定具体的规格文件。

为每个受影响的能力（新增/修改/删除）创建一个增量规格文件，路径为：

```
specs/<kebab-name>/spec.md
```

每个增量规格必须：

仅包含变更内容（仅展示差异），结构分为：

```
## ADDED Requirements
```
```
## MODIFIED Requirements
```
```
## REMOVED Requirements
```

要求部分使用规范性语言（MUST/SHALL）。
对于每个新增/修改/删除的要求，包含Given/When/Then场景：
- 至少一个正常流程场景（如适用）
- 至少一个边缘/失败场景
- 每个
```
#### Scenario:
```
  必须包含一个
```
##### Test Obligation
```
  块，内容包括：
```
Type
```
  （unit|integration|e2e）、
```
Test File
```
  、
```
Test Name
```
  、
```
Verify Command
```
  、
```
Expected (RED)
```
  和
```
Key Assertions
```
  。如果任何字段缺失，询问用户；请勿猜测。

编写完成后，打印：

```
Wrote specs: <path1>[, <path2> ...]
```

4. Re-check

4. 重新检查

After creating proposal or specs, re-run:

openspec status --change <change> --json

Stop the loop only when both artifacts show complete.

创建提案或规格后，重新运行：

openspec status --change <change> --json

仅当两个制品均显示为complete时，停止循环。

Minimal Output Contract

最小输出约定

Always show
```
Selected change: <change>
```
.
For each artifact you write, show exactly which artifact and the concrete path(s).
On any error, show the exact command that failed (including
```
--json
```
).

始终显示
```
Selected change: <change>
```
。
对于每个编写的制品，明确显示制品类型和具体路径。
发生任何错误时，显示失败的具体命令（包括
```
--json
```
参数）。

Common mistakes

常见错误

Using OpenSpec slash commands (anything starting with
```
/opsx
```
or
```
/openspec
```
) instead of the
```
openspec
```
CLI.
Treating wildcard
```
outputPath
```
(e.g.,
```
specs/**/spec.md
```
) as a real file path; always write concrete files like
```
specs/<kebab-name>/spec.md
```
.
Guessing
```
openspec
```
JSON fields instead of showing the JSON and asking the user.

使用OpenSpec斜杠命令（任何以
```
/opsx
```
或
```
/openspec
```
开头的命令）而非
```
openspec
```
CLI。
将通配符
```
outputPath
```
（如
```
specs/**/spec.md
```
）视为真实文件路径；应始终写入具体文件，如
```
specs/<kebab-name>/spec.md
```
。
猜测
```
openspec
```
JSON字段的含义，而非显示JSON内容并询问用户。