openspec-task-loop

OpenSpec 任务循环

子 Agent 架构

此技能采用严格的子 Agent 顺序流水线，每次迭代都会累积上下文，并依赖上一步的结果。模式：E（分阶段流水线）+ C（审查循环）。

Agent

Agent	角色	触发时机
spec-scaffolder	创建所有 OpenSpec 工件（proposal.md、design.md、tasks.md、specs/）	任务选择后
implementer	实现限定范围内的任务、更新复选框、运行验证	规格搭建完成后
verifier	独立检查质量门槛：范围原子性、验收标准、规格与测试的一致性	实现完成后
archiver	合并规格增量、移至归档目录、更新父级 tasks.md	验证通过后

顺序依赖

• 不并行执行：第 N+1 步依赖第 N 步完成
• 上下文累积：每个 Agent 都会读取之前的工件并加深理解
• 质量门槛：Verifier 确保每个阶段都稳妥后再继续

为何采用顺序执行：如果不采用这种分阶段方法，多次任务迭代（5–10 次）会显著降低推理质量。每一步都能建立信心并尽早发现问题。

环境检查

执行前：

1. 确认可访问仓库的 Git
2. 确认对 openspec/ 目录具有写入权限
3. 检查项目根目录中是否存在任务列表（tasks.md）
4. 确保 references/openspec-task-templates.md 可用

编辑前同步仓库（必需）

在现有仓库中创建、更新或删除文件之前，请将当前分支与远程仓库同步：

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

如果工作树不干净，请先暂存更改，再进行同步，然后恢复更改：

git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

如果缺少 origin、无法拉取，或 rebase/暂存时发生冲突，请停止并在继续前询问用户。

概述

将 OpenSpec 流程设为一个任务 = 一个变更。保持范围精简，生成工件、完成实现、验证并归档后，再开始下一个任务。

工作流决策

1. 如果当前编码工具支持 /opsx:* 命令：使用原生 OPSX 流程。
2. 如果不支持：使用手动备用方案，在 openspec/changes/<change-id>/ 下创建文件。

核心循环（单个任务）

对于 tasks.md 中选定的每个任务：

1. 只选择一个任务

   • 保持为一个原子价值单元（通常为 1–3 个开发日）。
   • 如果范围过大，继续前先拆分。

2. 创建任务范围内的变更

   • 使用变更 ID 格式：task-<task-id>-<short-slug>（示例：task-2-3-pin-crud）。

3. 使用 OpenSpec 工件进行规划

   • proposal.md：意图、范围、验收标准、不在范围内的内容。
   • specs/.../spec.md：需求以及 GIVEN/WHEN/THEN 场景。
   • design.md：实现方案和权衡。
   • tasks.md：此单个任务的实现清单。

4. 仅实现此任务范围内的内容

   • 不要加入无关的重构。
   • 随着工作完成更新复选框。

5. 归档前进行验证

   • 验证完整性、正确性和一致性。
   • 归档前修复关键的不匹配问题。

6. 归档并同步

   • 如有需要，合并规格增量。
   • 归档变更文件夹。
   • 将父项目任务标记为已完成。

原生 OPSX 命令流程

每个任务按以下顺序执行：

/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>

规则：

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

手动备用流程（不支持 /opsx）

如果无法使用斜杠命令：

1. 确保 OpenSpec 目录树存在（openspec/changes、openspec/specs）。
2. 创建一个变更文件夹，并搭建以下文件：
   • proposal.md
   • design.md
   • tasks.md
   • specs/<capability>/spec.md
3. 搭建任务工件之前，阅读 references/openspec-task-templates.md。
4. 实现任务并更新复选框。
5. 运行本地验证/测试。
6. 将规格增量合并到 openspec/specs/，并将变更移至 openspec/changes/archive/<date>-<change-id>/。

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

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

更新输出格式

报告进度时，请使用：

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

预期输出

每次完成任务迭代后，应看到：

• openspec/changes/<change-id>/ 下有一个 OpenSpec 变更文件夹，其中包含 proposal.md、design.md、tasks.md 和 specs/<capability>/spec.md
• 已实现的代码，所有任务复选框均已勾选
• 一份验证报告，确认范围的原子性、验收标准已满足，且规格与测试相匹配
• 变更文件夹已移至 openspec/changes/archive/<date>-<change-id>/
• 父级 tasks.md 已更新，并将已完成的任务标记为完成
• 按“更新输出格式”块所示的格式提交进度报告，其中显示 Status: archived

边界情况

• 任务过大：在开始之前，将其拆分为更小的原子化子任务（每个需 1–3 个开发日）；不要对过大的任务开始实施。
• 不支持 /opsx 命令：回退到 openspec/changes/ 下手动搭建文件，并遵循“手动回退路径”步骤。
• 缺少 references/openspec-task-templates.md：提醒用户并继续创建最精简的产物；请求提供模板文件，以提升脚手架质量。
• 验证器发现关键不匹配：阻止归档，指出具体差距，并在重新验证前修复；绝不归档未通过质量门禁的内容。
• 变基期间发生合并冲突：停止操作，向用户指出冲突；不要自动解决规格或实现文件中的更改。
• Tasks.md 不存在：在进入循环前，请用户提供或创建任务列表。

步骤完成报告

每完成一个主要步骤后，按以下格式输出状态报告：

◆ [Step Name] ([step N of M] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          √ pass (note if relevant)
  [Check 3]:          × fail — [reason]
  [Check 4]:          √ pass
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

根据该步骤实际验证的内容调整检查项名称。通过使用 √，失败使用 ×，简要补充说明使用 —。“Criteria”行概述满足了多少项验收标准。“Result”行给出总体结论。

选择（第 1 步，共 4 步）

◆ Selection (step 1 of 4 — task scoping)
··································································
  Task identified:        √ pass — task-2-3-pin-crud selected
  Scope bounded:          √ pass — 1-3 dev days, atomic unit
  Dependencies clear:     √ pass — no blockers in tasks.md
  [Criteria]:             √ 3/3 met
  ____________________________
  Result:                 PASS

规划（第 2 步，共 4 步）

◆ Planning (step 2 of 4 — spec scaffolding)
··································································
  Spec artifacts created: √ pass — proposal.md, design.md, tasks.md, spec.md
  Implementation planned: √ pass — approach and tradeoffs documented
  [Criteria]:             √ 2/2 met
  ____________________________
  Result:                 PASS

实施（第 3 步，共 4 步）

◆ Implementation (step 3 of 4 — code delivery)
··································································
  Code written:           √ pass — all checkboxes updated
  Tests pass:             × fail — 1 unit test failing
  Scope respected:        √ pass — no unrelated files changed
  [Criteria]:             √ 2/3 met
  ____________________________
  Result:                 PARTIAL

归档（第 4 步，共 4 步）

◆ Archive (step 4 of 4 — completion and sync)
··································································
  Artifacts synced:       √ pass — specs merged into openspec/specs/
  Quality gate passed:    √ pass — all 6 criteria met
  [Criteria]:             √ 2/2 met
  ____________________________
  Result:                 PASS

资源

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