openspec-task-loop

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenSpec Task Loop

OpenSpec 单任务循环

Overview

概述

Run OpenSpec as one task = one change. Keep scope tight, generate artifacts, implement, verify, and archive before moving to the next task.

以「一个任务对应一次变更」的方式运行OpenSpec。严格控制范围，生成工件、实现功能、验证结果，完成后再归档，之后再推进到下一个任务。

Workflow Decision

工作流选择

If
/opsx:*
commands are supported in the current coding tool: use native OPSX flow.
If not supported: use manual fallback by creating files under
```
openspec/changes/<change-id>/
```
.

如果当前编码工具支持
/opsx:*
命令：使用原生OPSX工作流。
如果不支持：通过在
```
openspec/changes/<change-id>/
```
目录下创建文件来进行手动回退。

Core Loop (Single Task)

核心循环（单任务）

For each selected task from

tasks.md

Select exactly one task
- Keep one atomic unit of value (usually 1–3 dev days).
- If too large, split before proceeding.
Create a task-scoped change
- Use change id format:
```
task-<task-id>-<short-slug>
```
  (example:
```
task-2-3-pin-crud
```
  ).
Plan with OpenSpec artifacts
- ```
proposal.md
```
  : intent, scope, acceptance criteria, out-of-scope.
- ```
specs/.../spec.md
```
  : requirements and GIVEN/WHEN/THEN scenarios.
- ```
design.md
```
  : implementation approach and tradeoffs.
- ```
tasks.md
```
  : implementation checklist for this single task.
Implement only this task scope
- Do not include unrelated refactors.
- Update checkboxes as work completes.
Verify before archive
- Validate completeness, correctness, coherence.
- Fix critical mismatches before archive.
Archive and sync
- Merge delta specs if needed.
- Archive change folder.
- Mark the parent project task complete.

对于从

tasks.md

中选定的每个任务：

精准选择一个任务
- 任务需为一个原子化的价值单元（通常耗时1–3个开发日）。
- 如果任务过大，需先拆分再推进。
创建任务专属的变更项
- 变更ID格式：
```
task-<task-id>-<short-slug>
```
  （示例：
```
task-2-3-pin-crud
```
  ）。
借助OpenSpec工件进行规划
- ```
proposal.md
```
  ：目标、范围、验收标准、排除范围。
- ```
specs/.../spec.md
```
  ：需求以及GIVEN/WHEN/THEN场景。
- ```
design.md
```
  ：实现方案与权衡分析。
- ```
tasks.md
```
  ：该单任务的实现检查清单。
仅实现当前任务范围的内容
- 不得包含无关的重构内容。
- 工作完成时更新复选框状态。
归档前进行验证
- 验证完整性、正确性与一致性。
- 归档前修复关键不匹配问题。
归档与同步
- 如有需要，合并增量规范。
- 归档变更文件夹。
- 标记父项目任务为已完成。

Native OPSX Command Path

原生OPSX命令流程

Use this sequence per task:

text

/opsx:new task-<task-id>-<slug>
/opsx:ff <change-id>          # or /opsx:continue for stepwise control
/opsx:apply <change-id>
/opsx:verify <change-id>
/opsx:archive <change-id>

Rules:

Prefer
```
/opsx:continue
```
when requirements are still unclear.
Prefer
```
/opsx:ff
```
when scope is clear and small.
If implementation reveals drift, update artifacts before continuing.

每个任务遵循以下命令序列：

text

/opsx:new task-<task-id>-<slug>
/opsx:ff <change-id>          # 或使用/opsx:continue进行分步控制
/opsx:apply <change-id>
/opsx:verify <change-id>
/opsx:archive <change-id>

规则：

当需求仍不明确时，优先使用
```
/opsx:continue
```
。
当范围清晰且较小时，优先使用
```
/opsx:ff
```
。
如果实现过程中发现偏差，需先更新工件再继续推进。

Manual Fallback Path (No /opsx Support)

手动回退流程（无/opsx支持）

If slash commands are unavailable:

Ensure OpenSpec tree exists (
```
openspec/changes
```
,
```
openspec/specs
```
).

Scaffold one change folder with:

```
proposal.md
```
```
design.md
```
```
tasks.md
```
```
specs/<capability>/spec.md
```

Use templates from
```
references/openspec-task-templates.md
```
.
Implement task and update checkboxes.
Run local validation/tests.

Merge spec deltas into

openspec/specs/

and move change to

openspec/changes/archive/<date>-<change-id>/

如果无法使用斜杠命令：

确保OpenSpec目录结构已存在（
```
openspec/changes
```
、
```
openspec/specs
```
）。

搭建一个变更文件夹，包含：

```
proposal.md
```
```
design.md
```
```
tasks.md
```
```
specs/<capability>/spec.md
```

使用
```
references/openspec-task-templates.md
```
中的模板。
实现任务并更新复选框。
运行本地验证/测试。
将规范增量合并到
```
openspec/specs/
```
中，并将变更文件夹移动到
```
openspec/changes/archive/<date>-<change-id>/
```
。

Quality Gate (must pass before archive)

质量门禁（归档前必须通过）

Scope remained single-task and atomic
Acceptance criteria satisfied
Spec scenarios reflected in tests or executable checks
No unrelated files changed
Parent
```
tasks.md
```
updated with completion state
Archive note includes what changed and why

范围保持单任务且原子化
验收标准已满足
规范场景已在测试或可执行检查中体现
未修改无关文件
父级
```
tasks.md
```
已更新完成状态
归档备注包含变更内容及原因

Output Format for Updates

进度更新输出格式

When reporting progress, use:

markdown

Task: <id + title>
Change: <openspec change id>
Status: planning | implementing | verifying | archived
Done:
- ...
Next:
- ...
Risks/Notes:
- ...

汇报进度时，请使用以下格式：

markdown

Task: <任务ID + 标题>
Change: <OpenSpec变更ID>
Status: planning | implementing | verifying | archived
Done:
- ...
Next:
- ...
Risks/Notes:
- ...

Resources

资源

```
references/openspec-task-templates.md
```
— proposal/spec/design/tasks templates for manual mode.
```
scripts/new_task_change.sh
```
— optional scaffold script for manual mode.

```
references/openspec-task-templates.md
```
— 手动模式下的提案/规范/设计/任务模板。
```
scripts/new_task_change.sh
```
— 手动模式下可选的脚手架脚本。