repo-task-proof-loop

Repo 任务证明闭环

当用户希望针对一项复杂编码任务采用可重复、可审计的实现工作流时，尤其是需要在 .agent/tasks/<TASK_ID>/ 中留下仓库内证明的功能、重构、迁移或 Bug 修复，请使用此技能。

此工作流创建的所有任务产物都必须保留在仓库内。

以下示例中的 scripts/task_loop.py 路径相对于此技能的根目录。运行它时，Shell 的工作目录必须位于目标仓库内。

此技能的用途

1. 在 .agent/tasks/<TASK_ID>/ 下初始化严格的仓库内任务文件夹
2. 创建或更新所需的产物文件
3. 将项目级 Codex 和 Claude 子 Agent 模板安装到 .codex/agents/ 和 .claude/agents/
4. 更新仓库根目录下的 Codex 基准文件 AGENTS.md，以及仓库的 Claude 指南文件（CLAUDE.md 或 .claude/CLAUDE.md），添加说明此工作流的托管代码块
5. 引导 Agent 执行严格的闭环流程：
   • 冻结规范
   • 构建器实现
   • 打包证据
   • 全新验证
   • 最小化修复
   • 再次全新验证，直至 PASS

参见：

• references/REFERENCE.md
• references/COMMANDS.md
• references/SUBAGENTS.md
• references/SCHEMAS.md

此技能支持的命令

用户调用此技能时，将以下词语视为命令：

• init <TASK_ID>：创建 .agent/tasks/<TASK_ID>/，安装或刷新子 Agent 模板，并更新 AGENTS.md 和仓库的 Claude 指南文件
• freeze <TASK_ID>：根据用户任务、任务文件和仓库指南，创建或完善 spec.md
• build <TASK_ID>：按照已冻结的规范实现任务
• evidence <TASK_ID>：创建或刷新 evidence.md、evidence.json 和原始产物，不更改生产代码
• verify <TASK_ID>：执行全新的验证，并写入 verdict.json，必要时写入 problems.md
• fix <TASK_ID>：根据 problems.md 应用最小且安全的修复集，然后刷新证据包
• run <TASK_ID>：从冻结规范开始执行整个闭环，直至完成验证
• status <TASK_ID>：汇总当前产物状态

如果用户未指定命令，请根据仓库状态推断下一步：

• 如果任务文件夹不存在，先运行 init。如果用户明确表示只需初始化，则到此为止。否则，在 init 成功且 .agent/tasks/<TASK_ID>/spec.md 存在后，应在同一轮中重新评估仓库状态并继续。不要将 init 与 freeze、build、evidence、verify、fix、validate、status 或子 Agent 工作重叠执行。
• 如果缺少 spec.md 或其内容仅为占位文本，则执行 freeze
• 如果实现尚未完成，则执行 build
• 如果证据过时或缺失，则执行 evidence
• 如果没有最新的验证结果，则执行 verify
• 如果结果不是 PASS，则执行 fix

初始化步骤

在仓库根目录或仓库内的当前工作目录中运行附带的初始化程序：

scripts/task_loop.py init --task-id <TASK_ID>

可选的任务种子：

scripts/task_loop.py init --task-id <TASK_ID> --task-file path/to/task.md
scripts/task_loop.py init --task-id <TASK_ID> --task-text "User task text"

初始化程序将：

• 解析仓库根目录
• 创建 .agent/tasks/<TASK_ID>/
• 创建所有必需的产物，包括 raw/ 下的占位文件
• 安装项目级子 Agent 文件
• 在 AGENTS.md 和仓库的 Claude 指南文件中插入或刷新托管的工作流区块

对于 Codex，初始化程序会将托管的工作流区块保留在仓库根目录的 AGENTS.md 中。Codex 还支持 AGENTS.override.md 和已配置的备用指南文件名；更靠近代码的嵌套文件仍优先，而此技能有意不会覆盖这些文件。 如果 init 在正在运行的 Codex 会话中创建或重写了 AGENTS.md，请启动新的 Codex 会话，再依赖更新后的说明。Codex 会在会话启动时载入项目文档指南的快照。

对于 Claude Code，初始化程序会将托管的工作流区块保留在仓库根目录的 CLAUDE.md 中。Claude Code 还支持 .claude/CLAUDE.md、.claude/rules/*.md 和 CLAUDE.local.md，但此技能将根目录的 CLAUDE.md 视为主要项目指南，因为 Claude 会直接显示该文件。

在 Claude Code 中，如果 init 刚在当前会话期间写入或刷新了 .claude/agents/*，请勿假设这些更新后的 Agent 已可在会话中途使用。

将 init 视为串行前置步骤。绝不要让它与 freeze、build、evidence、verify、fix、validate、status 或子 Agent 的启动并行执行。

大型任务的默认工作流

对于大型任务，保持面向用户的请求简单。在 Codex 中，除非用户明确要求委派或并行 Agent 工作，否则应继续串行执行；获得授权后，如果当前产品界面支持委派且任务适合采用该方式，技能可自动选择内部子任务设置。

首选的委派顺序

1. 如有需要，运行 init <TASK_ID>。等待其完成，然后确认 .agent/tasks/<TASK_ID>/spec.md 和仓库本地任务结构均已存在，再继续。
2. 仅在 init 完成后，启动且只启动一个无规范冻结子 Agent，并等待它完成
3. 启动且只启动一个构建子 Agent，让它负责实现
4. 继续使用同一个构建子 Agent 来打包证据
5. 启动且只启动一个全新的验证子 Agent，并等待它完成
6. 如果结论不是 PASS，启动且只启动一个修复子 Agent
7. 再次启动一个全新的验证子 Agent
8. 重复步骤 6–7，直到验证器返回 PASS 或用户终止循环

Codex 自适应扇出

仅在用户已明确授权 Codex 委派，且任务足够广、适合进行有限并行工作时使用此模式。对于范围较窄的任务，请使用上文更简单的串行流程。

适用场景：

• 规范稳定之前，必须回答多个相互独立的代码库问题
• 实现可以拆分为互不重叠的写入范围
• 证明需要在不同方面进行多项相互独立的只读检查

Codex 模式：

1. init 保持串行。
2. 如果任务仍有歧义，则最多并行派出 3 个内置 explorer 子 Agent。为每个子 Agent 指定一个问题、子系统或路径范围。等待它们完成，然后冻结规范。
3. 派出一个规范冻结子 Agent，并等待其完成。
4. 派出一个 task-builder 子 Agent，负责集成。
5. 如果实现可以清晰拆分，父 Agent 也可以并行派出有限数量的内置 worker 子 Agent。每个 worker 都必须拥有明确的文件或模块范围，并且不得写入 evidence.md、evidence.json、verdict.json 或 problems.md。
6. 使用 send_input 或等效的后续交互接口，让集成构建器持续处理证据打包。构建器仍是证据包的唯一负责人。
7. 如果需要额外证明，父 Agent 可以派出少量只读 explorer 子 Agent，在并行状态下重新运行互不重叠的检查，或检查不同的证明缺口。这些子 Agent 可以报告命令、输出和发现，但不得写入 verdict.json。
8. 每个验证轮次都恰好运行一个全新的验证器子 Agent。

平台行为

• 在 Codex 中，执行 init 后，保持常规流程串行，并优先使用自动模式。除非委派细节会实质影响工作，否则不要主动提及。
• 在 Codex 中，只有用户明确要求使用子 Agent、委派或并行 Agent 工作时，才启动有界子 Agent。
• 在 Codex 中，获得委派授权后，技能可以选择匹配的子角色，并决定逐个启动子 Agent 还是进行有界扇出。用户无需指定具体的子角色或斜杠命令。
• 在 Codex 中，启动子 Agent 仍是父级协调者的显式操作。如果当前 Codex 界面不支持委派，仅当这会实质影响工作时才简要说明，然后继续串行执行。
• 在 Codex 中，保持任务树扁平。父会话应直接启动研究、构建、修复和验证子 Agent，而不是让一个自定义任务子 Agent 再去协调更多子 Agent。
• 在 Codex 中，获得委派授权后，根据已冻结的规范、仓库结构和当前委派界面，在逐个启动子 Agent 与有界扇出之间做出选择。无论采用哪种方式，都必须串行执行 init、证据归属和每一轮验证。
• 在 Codex 中，辅助 Agent 的扇出应适度，并按轮次进行。优先一次并行启动最多 3 个辅助子 Agent，等待这一轮完成后，再决定下一阶段。
• 在 Codex 中，进行只读仓库发现和证明探测时，优先选择内置的 explorer。如果可以明确分配所有权，内置的 worker 适合负责边界清晰、互不重叠的实现任务或重新运行检查。
• 在 Codex 中，通过向正在运行的构建子 Agent 发送后续指令，让它复用现有会话来整理证据。验证轮次必须使用新的子 Agent 或新会话；不能通过恢复先前的验证子 Agent 来满足验证新鲜度要求。有意复用其上下文时，可以重复使用或恢复构建和修复子 Agent。
• 在 Codex 中，复用或恢复子 Agent 前，先检查当前子线程列表。在 Codex CLI 中使用 /agent，或使用当前 Codex 产品界面中任何等效的子线程清单功能。
• 在 Codex 中，update_plan 提供的计划／待办清单 UI 仅是可选的会话指导。它有助于实时展示进度，但不是此工作流的事实依据。
• 在 Claude Code 中，执行 init 后，技能应决定是留在主线程，还是让 Claude 主会话将当前阶段自动委派给匹配的内置子 Agent 或项目子 Agent。用户无需另行指定某个 Claude 子 Agent 或委派模式。
• 在 Claude Code 中，TodoWrite 或可见的任务／待办 UI 仅用于显示会话范围内的进度，是可选功能。它有助于跟踪当前会话的实时进度，但不是此工作流的事实依据。
• 在 Claude Code 中，优先使用 .claude/agents/ 中已安装的项目子 Agent，并将其描述写成对应证明循环阶段的主动触发条件。Claude 主会话会根据任务请求、子 Agent 描述和当前上下文进行分派，因此应使用清晰的自然语言描述各阶段提示词。默认情况下，证据阶段复用同一个构建子 Agent。只有原构建会话不可用或你有意将其丢弃时，才以仅处理证据的模式启动新的构建子 Agent。如果 init 刚在当前 Claude 会话中刷新了 .claude/agents/*，则应退回主线程或使用已经可见的 Agent，不要假设刷新后的 Agent 立即可用。
• 在 Claude Code 中，保持协调结构扁平：主会话自动委派没有问题，但证明循环工作流中的 Agent 本身应为叶子角色。父会话应负责控制证明循环各阶段的转换，而不是让一个自定义任务 Agent 再去启动另一个 Agent。
• 在 Claude Code 中，规范的持久状态始终是 .agent/tasks/<TASK_ID>/ 下的仓库本地制品集，尤其是 spec.md、evidence.md、evidence.json、verdict.json 和 problems.md。
• 如果子 Agent 不可用，则应通过不同会话或当前会话中清晰的模式切换，保留相同的角色分工。 使用 references/COMMANDS.md 中的准确角色提示词。

规格冻结要求

spec.md 必须至少包含：

• 原始任务说明
• 明确标记为 AC1、AC2……的验收标准
• 约束
• 非目标

也可以包含：

• 仓库指南来源
• 验证计划
• 根据用户请求谨慎确定的假设

规格冻结期间不得编辑生产代码。

证据整理要求

evidence.md 和 evidence.json 必须分别使用以下状态判定每项验收标准：

• PASS
• FAIL
• UNKNOWN

证据整理可以运行尚未执行的检查，但不得继续修改生产代码。

每个 PASS 都必须引用具体证据，例如：

• 文件路径
• 运行的命令
• 退出代码
• 输出摘要
• raw/ 下的产物路径

除非每项验收标准都为 PASS，否则不得在证据包中声称总体结果为 PASS。

新鲜验证要求

验证者必须是全新会话或全新的子 Agent。 在 Codex 中，不得通过恢复先前的验证者子任务来满足此要求。

验证者必须依据当前仓库状态和当前重新运行的结果进行判定，而非依赖构建者的叙述。

验证者需写入：

• .agent/tasks/<TASK_ID>/verdict.json
• 仅当总体判定不是 PASS 时写入 .agent/tasks/<TASK_ID>/problems.md

对于每项非 PASS 的标准，problems.md 必须包含：

• 标准 ID 和文本
• 状态
• 未能证明的原因
• 最简复现步骤
• 预期结果与实际结果
• 受影响的文件
• 最小安全修复方案
• 1 至 3 句话的修正提示

验证者不得修改生产代码，也不得补充证据包。

修复者要求

修复者只能读取：

• spec.md
• verdict.json
• problems.md

修复者必须：

• 编辑前在代码库中重新确认列出的问题
• 采用最小安全变更集
• 避免导致已通过的标准回归
• 重新生成 evidence.md、evidence.json 和原始产物
• 停止操作，不得写入最终签署结果

验证

在声称工作流已正确初始化或产物集已完整之前，运行：

scripts/task_loop.py validate --task-id <TASK_ID>

只有在 init 完全结束后才能运行 validate。如果报告显示初始化正在进行，请等待后重新运行，不要将该结果视为稳定的任务失败。

快速查看摘要：

scripts/task_loop.py status --task-id <TASK_ID>

只有在 init 完全结束后，且需要稳定的任务状态时，才能运行 status。如果报告显示 init_in_progress: true，应视为需要稍后重试。

防护措施

• 将 .agent/tasks/<TASK_ID>/ 保留在仓库内
• 将 Codex 待办事项／检查清单 UI 仅视为临时进度展示；持久化工作流状态保存在 .agent/tasks/<TASK_ID>/ 中
• 除非每项验收标准都为 PASS，否则绝不得声称任务已完成
• 分离评估者与修复者角色
• 控制 Codex 并行扩展的层级和范围。并行助手可以为验证循环提供信息，但证据必须由一名构建者负责，判定必须由一名全新的验证者负责。
• 确保验证者是全新的
• 修复时优先采用最小且有充分依据的差异
• 保留 AGENTS.md 和仓库选定的 Claude 指南文件中托管区块以外的现有用户指南