superspec-implementation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Superspec Implementation (Apply + Validate)

Superspec 实施（执行+验证）

Rules (non-negotiable)

规则（不可协商）

Drive OpenSpec via CLI only (NO OpenSpec slash commands; i.e., commands starting with
```
/opsx
```
or
```
/openspec
```
).
It is OK to tell the user to run Superspec skills like
```
/superspec-plan
```
; only OpenSpec slash commands are disallowed.
Prefer JSON output for every OpenSpec call (use
```
--json
```
).
Only implement what the tasks/specs require; do not expand scope.
Do not proceed if required tasks/artifacts are missing or blocked.

仅通过CLI驱动OpenSpec（禁止使用OpenSpec斜杠命令；即不要使用以
```
/opsx
```
或
```
/openspec
```
开头的命令）。
可以告知用户运行Superspec技能，如
```
/superspec-plan
```
；仅禁止OpenSpec斜杠命令。
每次调用OpenSpec时优先使用JSON输出（使用
```
--json
```
参数）。
仅实施任务/规范要求的内容；不要扩展范围。
如果必要的任务/工件缺失或被阻塞，请勿继续执行。

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.

Always print:

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

如果用户提供了变更名称，将其作为
```
<change>
```
使用。
否则运行：
- ```
openspec list --json
```
  请用户从JSON输出中确认/选择一个变更名称。

始终打印：

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

Block If Tasks Missing/Blocked

若任务缺失/被阻塞则终止

Run:

openspec status --change <change> --json

If the JSON clearly indicates
```
tasks
```
is missing or blocked, STOP and tell the user to run
```
/superspec-plan
```
.

If the JSON does not clearly indicate whether

tasks

is ready/blocked, show the JSON and ask the user what the status fields mean; do not guess.

运行：

openspec status --change <change> --json

如果JSON明确显示
```
tasks
```
缺失或被阻塞，立即停止并告知用户运行
```
/superspec-plan
```
。

如果JSON未明确显示

tasks

是否就绪/被阻塞，展示该JSON并询问用户状态字段的含义；请勿猜测。

Apply Instructions (gating/progress)

执行说明（门控/进度）

Run:

openspec instructions apply --change <change> --json

From the JSON, extract any gating/progress indicators if present (e.g., tracked file path, completion rules, progress counts).

If progress information exists, report it during implementation.
If the JSON is unclear, show it; do not guess.

运行：

openspec instructions apply --change <change> --json

从JSON中提取任何现有的门控/进度指示器（例如，跟踪文件路径、完成规则、进度计数）。

如果存在进度信息，在实施过程中进行报告。
如果JSON内容不明确，展示该JSON；请勿猜测。

Implement Tasks (Mechanical)

执行任务（机械性操作）

Before executing any task line, follow

/superspec-tdd

as a strict enforcement subroutine.

Open the
```
tasks.md
```
for the selected change.
- If you cannot determine the path, use the status/apply JSON to locate it.
For each unchecked task line (
```
- [ ] ...
```
) in order:
- Parse tags on the line. If tags are missing or unknown, STOP and ask the user.
- Execute mechanically based on tags:
  - ```
  [TDD][RED]
```
  : write tests only (no production code).
- ```
[TDD][VERIFY_RED]
```
    : extract the command from the same line after
```
Run:
```
    and run it exactly; confirm FAIL contains the
```
Expected (RED)
```
    substring.
  - ```
  [TDD][GREEN]
```
  : implement minimal production code to satisfy the Scenario.
- ```
[TDD][VERIFY_GREEN]
```
    : extract the command from the same line after
```
Run:
```
    and run it exactly; confirm PASS.
  - ```
  [TDD][REFACTOR]
```
  : refactor without behavior change; then re-run the same Verify Command used for the Scenario and confirm it still passes.
- ```
[NON-TDD][DO]
```
    : perform the described non-behavior change (docs-only/config-only (no behavior change)/generated outputs/formatting-renaming only).
  - ```
  [NON-TDD][VERIFY]
```
  : extract the command from the same line after
```
  Verify:
```
  and run it exactly.
- Do not invent commands. If a VERIFY task does not contain an executable command after
```
Run:
```
  or
```
Verify:
```
  , STOP and ask the user.
- Check off the task by changing it to
```
- [x] ...
```
  .

Keep edits small and surgical.

在执行任何任务行之前，严格遵循

/superspec-tdd

作为强制子流程。

打开所选变更对应的
```
tasks.md
```
文件。
- 如果无法确定路径，使用状态/执行JSON来定位它。
按顺序处理每个未勾选的任务行（
```
- [ ] ...
```
）：
- 解析该行的标签。如果标签缺失或未知，停止并询问用户。
- 根据标签进行机械性执行：
  - ```
  [TDD][RED]
```
  ：仅编写测试（不要编写生产代码）。
- ```
[TDD][VERIFY_RED]
```
    ：从该行的
```
Run:
```
    后提取命令并精确运行；确认失败信息中包含
```
Expected (RED)
```
    子字符串。
  - ```
  [TDD][GREEN]
```
  ：编写最少的生产代码以满足场景要求。
- ```
[TDD][VERIFY_GREEN]
```
    ：从该行的
```
Run:
```
    后提取命令并精确运行；确认通过。
  - ```
  [TDD][REFACTOR]
```
  ：在不改变行为的前提下进行重构；然后重新运行该场景对应的验证命令并确认仍然通过。
- ```
[NON-TDD][DO]
```
    ：执行描述的非行为变更（仅文档/仅配置（不改变行为）/生成输出/仅格式重命名）。
  - ```
  [NON-TDD][VERIFY]
```
  ：从该行的
```
  Verify:
```
  后提取命令并精确运行。
- 不要自行创建命令。如果验证任务在
```
Run:
```
  或
```
Verify:
```
  后没有可执行的命令，停止并询问用户。
- 通过将任务行改为
```
- [x] ...
```
  来标记该任务已完成。

保持编辑小而精准。

Validate

验证

Run:
- ```
openspec validate --all --json
```
If errors exist:
- Fix them.
- Re-run
```
openspec validate --all --json
```
  .
Warnings are informational; do not block unless they indicate a real defect.

运行：
- ```
openspec validate --all --json
```
如果存在错误：
- 修复错误。
- 重新运行
```
openspec validate --all --json
```
  。
警告仅作为信息参考；除非它们指示实际缺陷，否则不要终止流程。

Minimal Output Contract

最小输出约定

Always show
```
Selected change: <change>
```
.
If you need user input (e.g., selecting a change, unclear JSON fields), show only the minimal JSON needed.
Report task progress if apply/status JSON provides it.
Report validate summary:
- valid/invalid counts
- first few errors (if any)

始终显示
```
Selected change: <change>
```
。
如果需要用户输入（例如，选择变更、不明确的JSON字段），仅展示必要的最小JSON内容。
如果执行/状态JSON提供了进度信息，报告任务进度。
报告验证摘要：
- 有效/无效计数
- 前几个错误（如果有）

Common mistakes

常见错误

Using OpenSpec slash commands instead of
```
openspec
```
CLI.
Starting implementation when
```
tasks
```
is missing/blocked (must send user to
```
/superspec-plan
```
).
Checking off tasks without adding tests that cover delta spec scenarios.
Running
```
openspec validate
```
without
```
--json
```
and losing actionable error details.

使用OpenSpec斜杠命令而非
```
openspec
```
CLI。
在
```
tasks
```
缺失/被阻塞时开始实施（必须引导用户运行
```
/superspec-plan
```
）。
在未添加覆盖增量规范场景的测试的情况下标记任务为完成。
运行
```
openspec validate
```
时未使用
```
--json
```
参数，导致丢失可操作的错误详情。