仓库任务证明循环

当用户希望为一个非平凡的编码任务（尤其是应留下仓库本地证明 .agent/tasks/<TASK_ID>/ 的功能、重构、迁移或Bug修复）获得可重复、可审计的实现工作流时，使用此技能。

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

当下面示例提及 scripts/task_loop.py 时，该路径相对于此技能根目录。请在目标仓库的 shell 工作目录下运行它。

此技能的功能

在 .agent/tasks/<TASK_ID>/ 下初始化一个严格的仓库本地任务文件夹
填充或更新所需的工件文件
将项目范围的 Codex 和 Claude 子代理模板安装到 .codex/agents/ 和 .claude/agents/
使用解释工作流的托管块更新仓库根目录的 AGENTS.md（Codex 基线）以及仓库的 Claude 指南文件（CLAUDE.md 或 .claude/CLAUDE.md）
引导代理经过一个严格的循环：
- 规范冻结
- 构建器实现
- 证据打包
- 全新验证
- 最小修复
- 再次全新验证直到 PASS

请参阅:

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

此技能支持的命令

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

init <TASK_ID>: 创建 .agent/tasks/<TASK_ID>/，安装或刷新子代理模板，并更新 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 或子代理工作重叠。
如果 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 "用户任务文本"

初始化器将:

解析仓库根目录
创建 .agent/tasks/<TASK_ID>/
创建所有必需工件，包括 raw/ 下的占位符
安装项目范围的子代理文件
在 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/*，不要假设这些更新的代理在会话中已经可用。

将 init 视为串行先决条件。切勿将其与 freeze、build、evidence、verify、fix、validate、status 或子代理生成重叠。

大型任务默认工作流

对于大型任务，保持用户界面请求简单。在 Codex 中，除非用户明确要求委托或并行代理工作，否则继续串行处理；获得该授权后，当当前产品表面支持委托且任务形态需要时，技能可以自动选择内部子设置。

首选委托序列

如果需要，运行 init <TASK_ID>。等待其完成，然后确认 .agent/tasks/<TASK_ID>/spec.md 和仓库本地任务结构存在后再继续。
仅在 init 完成后，生成恰好一个规范冻结子代理并等待之
生成恰好一个构建器子代理并让其实现
继续使用同一个构建器会话进行证据打包
生成恰好一个全新的验证器子代理并等待之
如果判定结果不是 PASS，生成恰好一个修复器子代理
再次生成恰好一个全新的验证器子代理
重复步骤 6-7，直到验证器返回 PASS 或用户停止循环

Codex 自适应扇出

仅当用户明确授权 Codex 委托且任务范围足够广，适合有限并行工作时，才使用此模式。对于范围狭窄的任务，请使用上面的简单串行序列。

适合的场景:

在规范稳定之前，需要回答多个独立的代码库问题
实现可以拆分为不相交的写入范围
证明需要跨不同表面的多个独立只读检查

Codex 模式:

init 保持串行。
如果任务仍然不明确，并行扇出最多 3 个内置的 explorer 子代理。给每个子代理一个单一问题、子系统或路径范围。等待它们，然后冻结规范。
生成一个规范冻结子代理并等待之。
生成一个 task-builder 子代理作为集成所有者。
如果实现清晰地拆分，父代理也可以并行扇出有限的内置 worker 子代理。每个 worker 必须有明确的文件或模块所有权，并且不得写入 evidence.md、evidence.json、verdict.json 或 problems.md。
使用 send_input 或等效的后续界面保持集成构建器存活以进行证据打包。构建器仍然是证据包的单一所有者。
如果需要额外的证明，父代理可以扇出一个小的有限只读 explorer 子代理集，以并行地重新运行不相交的检查或检查独立的证明缺口。这些子代理可以报告命令、输出和发现，但不能写入 verdict.json。
每次验证遍历只运行恰好一个全新的验证器子代理。

平台行为

在 Codex 中，init 之后保持常规路径串行且自动模式优先。避免暴露委托内部细节，除非它们实质上影响工作。
在 Codex 中，只有当用户明确要求子代理、委托或并行代理工作时，才生成有限的子代理。
在 Codex 中，一旦授权委托，技能可以选择匹配的子角色以及是保持一次一个子代理还是使用有限的扇出。用户不应需要指定特定的子角色或斜杠命令。
在 Codex 中，子代理生成仍然是显式的父协调器操作。如果当前的 Codex 界面阻止委托，仅在它实质影响工作时简短说明，然后继续串行处理。
在 Codex 中，保持任务树浅层。父会话应直接生成研究、构建器、修复器和验证器子代理，而不是要求一个自定义任务子代理去协调更多子代理。
在 Codex 中，一旦授权委托，根据冻结的规范、仓库形状和当前委托界面，在一次一个子代理的委托和有限扇出之间选择。无论哪种方式，都保持 init、证据所有权和每次验证遍历为串行化。
在 Codex 中，保持助手扇出适度且基于批次。最好一次最多并行 3 个助手的子代理，等待该批次完成，然后决定下一阶段。
在 Codex 中，内置的 explorer 是只读仓库发现和证明探测的首选。内置的 worker 适用于有限的不相交实现或检查重跑，当你可以分配明确的所有权时。
在 Codex 中，通过向活的构建器子代理发送后续指令来重用它进行证据打包。验证器遍历必须使用全新的子代理或全新会话；不要通过恢复先前的验证器来满足验证器的新鲜度要求。构建器与修复器子代理可以有意图地重用或恢复以利用其上下文。
在 Codex 中，在重用或恢复子代理之前，检查当前的子线程列表。在 Codex CLI 中使用 /agent 或当前 Codex 产品界面中任何等效的子线程清单界面。
在 Codex 中，来自 update_plan 的计划/待办清单 UI 仅是可选的会话指南。它对于实时进度显示有用，但不是此工作流的真实来源。
在 Claude Code 中，技能应决定是留在主线程上，还是让主 Claude 会话在 init 之后自动将当前阶段委托给匹配的内置或项目子代理。用户不应需要单独请求特定的 Claude 子代理或委托模式。
在 Claude Code 中，TodoWrite 或可见的任务/待办 UI 仅是可选的会话范围进度显示。它有助于当前会话的实时跟踪，但不是此工作流的真实来源。
在 Claude Code 中，优先使用安装在 .claude/agents/ 中的项目子代理，其描述应写为匹配证明循环阶段的主动触发条件。Claude 的主会话根据任务请求、子代理描述和当前上下文路由，因此保持每个阶段提示清晰自然。默认情况下，为证据步骤重用同一个构建器子代理。仅当原始构建器会话不可用或你有意放弃它时，才以纯证据模式运行新的构建器。如果 init 在当前 Claude 会话期间刚刚刷新了 .claude/agents/*，则回退到主线程或已有的代理，而不是假设刷新后的代理立即可用。
在 Claude Code 中，保持编排扁平化：主会话的自动委托是可以的，但证明循环工作流代理本身是叶子角色。父会话应拥有证明循环的阶段转换，而不是要求一个自定义任务代理去生成另一个。
在 Claude Code 中，规范的持久状态始终是 .agent/tasks/<TASK_ID>/ 下的仓库本地工件集，特别是 spec.md、evidence.md、evidence.json、verdict.json 和 problems.md。
如果子代理不可用，则在当前会话中的单独会话或清晰模式变更之间保持相同的角色分离。

使用来自 references/COMMANDS.md 的确切角色提示。

规范冻结要求

spec.md 必须至少包含:

原始任务声明
标记为 AC1、AC2、... 的明确验收标准
约束条件
非目标

它还可以包括:

仓库指南来源
验证计划
根据用户请求狭义解析的假设

在规范冻结期间不要编辑生产代码。

证据打包要求

evidence.md 和 evidence.json 必须使用以下之一独立评判每个验收标准:

PASS
FAIL
UNKNOWN

证据打包可以运行缺失的检查，但不得持续更改生产代码。

每个 PASS 必须引用具体的证明，例如:

文件路径
运行的命令
退出码
输出摘要
raw/ 下的工件路径

除非每个验收标准都是 PASS，否则不要在证据包中声明总体 PASS。

全新验证要求

验证器必须是全新会话或全新子代理。在 Codex 中，不要通过恢复先前的验证器子代理来满足此要求。

验证器必须判断当前的仓库状态和当前的重跑结果，而不是构建器的叙述。

验证器写入:

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

problems.md 对于每个非 PASS 的标准必须包括:

标准 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 仅视为短暂的进度指示

…

[为翻译截断]

仓库任务证明循环 (Repo Task Proof Loop)