Adonis0123/adonis-skills / skills/task-completion-loop
task-completion-loop
UnverifiedFinish an existing named plan/spec or clearly bounded unfinished non-trivial coding task through the explicit task-completion-loop: work ledger, Goal, implementation proof, agentic review, architecture hardening, and a fresh Claude audit. Use only for the whole requested pipeline, not ordinary implementation, planning, or review.
Task Completion Loop
把已有 plan / spec / 半成品收敛为同一份最终代码快照上的可验证终态。
本 Skill 是薄编排:依赖 skill 拥有内部协议;本 Skill 只管理任务账本、调用顺序、证据新鲜度、授权边界和停止条件。
入口与授权
同时具备才启动:
- Git 仓库,以及命名 plan/spec 或可从当前代码确定的明确范围。
- 明确的完整闭环实现请求。只要 Goal、只要 review-fix-re-review、只要架构加固、普通实现、纯讨论、纯 review 或只读诊断 → 不是本 Loop。
先从文档与代码解析范围。仍无法安全确定时,只问一个范围问题并停止。禁止默认全仓库。
实现请求授权修改冻结范围内的 working tree;除非用户明确要求只读或禁止编辑。它不授权:
git add、commit、push、merge、rebase、branch/worktree 创建;- PR、issue、评论、消息、任务、API 数据、部署、生产写;
- 排除路径或冻结范围外修改。
agentic-review-handoff 所需的 .review-handoff/** 与幂等 $GIT_COMMON_DIR/info/exclude 条目是本闭环的本地协议产物,不是交付动作;预检时披露,完成报告中记录。用户明确禁止 .git/** 写时,在源码修改前返回 HUMAN_GATE。
能力预检
始终要求:
| 能力 | 用途 |
|---|---|
goal-gate | Goal 决策与运行时激活 |
agentic-review-handoff | 独立 review-fix-re-review |
architecture-hardening-loop | 有界扫描、修复、复核、复扫 |
| 真实 Peer A 会话 | 独立立场与交叉质疑 |
| 真实 Peer B 会话 | 独立立场与交叉质疑 |
| 真实 Claude Code 会话 | 盲审 |
仅在用户显式要求 grill-with-docs,或预检发现仍有用户拥有的产品/领域决策时,要求并调用 grill-with-docs(其 frontmatter 默认 disable-model-invocation: true;文件可读即按父会话路径加载)。
在讨论、Goal、源码修改前:
- 解析每个 skill 及其传递硬依赖(特别是
architecture-hardening-loop的 scanner、codebase-design、只读 delegation、非宿主 Reviewer 的真实 adapter)。invocation policy 与父会话执行路径沿用architecture-hardening-loop「硬依赖与 runtime 能力」的规则:用户点名本 Loop 即授权硬依赖按用途嵌套调用;文件可读即可由父会话执行;未安装/不可读、合同不兼容或 worker/工具无法执行才算缺失。细则见 decision-and-terminal-gates.md 的 Preflight policy。 - 选定 Peer A、Peer B(见下文「Peer 选择」),对每个 Peer 用
agentic-review-handoff的review-loop consult --repo <root> --peer <product> [--fallback <未用的产品>] --question-file <md>完成一次真实往返(用户点名账号如codex002/cc002/grok002时加--peer-command=<名字>),并用review-loop sessions --repo <root> --product=<product>取回可恢复句柄;Phase 1 A 的首条成功往返即可充当此证据,不单独占一轮。每个 Peer 都须能以 adapter 的只读控制启动;盲审用的 Claude 同样。只有名字、catalog 条目或 CLI 文件存在不算可用。 - 确认 review 协议产物可写,且不与用户的
.git/**限制冲突。
Peer 选择:Peer A、Peer B 是两个和宿主不同的产品,按 agentic-review-handoff 保存的 Reviewer 偏好顺序(review-loop prefs,默认 claude,codex,grok)去掉宿主后取前两个:三方收敛要三个不同产品,所以这里总是跳过宿主,偏好里的 skipHost 不影响。例如默认偏好下 Claude 宿主 → Codex + Grok;Codex 宿主 → Claude + Grok;Grok 宿主 → Claude + Codex。用户点名的产品或账号优先。consult 可直接传 --host=<宿主> --skip-host,由脚本按偏好选。某个 Peer 超时,脚本按 --fallback 换到两个 Peer 和宿主都没用到的已安装产品(结果里的 fallbacks);没有这样的产品就不换人,按下文超时规则处理。不拿另一位 Peer 的产品顶替,否则两份立场就不独立了。
缺少始终要求的能力,或缺少本轮实际需要的条件能力:
Task Completion Result
- Result: MISSING_DEPENDENCIES
- Missing: <exact skill, dependency chain, or runtime capability>
- Stop point: before discussion, Goal activation, and source changes
- Substitution/install: none; no generic agent impersonation, copied skill logic, or automatic install
- Work started: no
禁止用通用 subagent 冒充 Peer 或盲审的 Claude、伪造会话或复制缺失 skill 逻辑:三方收敛的价值来自真正独立的模型立场,冒充会让交叉质疑退化为自我评论。代装依赖属于外部写,见「入口与授权」。
状态机
预检与任务账本
-> 三方交叉质疑
-> 条件式 grill-with-docs(用户决策)
-> Goal Gate
-> 实现全部 PENDING + 验证
-> agentic-review-handoff
-> architecture-hardening-loop = NO_ACTIONABLE_FINDINGS
-> 全新只读 Claude 盲审
-> Fix:修、验、重跑下游门禁、再盲审
-> 仅 Backlog / Reject:完成 Goal
-> COMPLETED
任意阶段的出口:
缺能力 -> MISSING_DEPENDENCIES
用户决策 / 权限 / 范围扩张 -> HUMAN_GATE
证据缺失、过期或外部会话超时 -> UNVERIFIED
Phase 0:任务账本与证据
- 读取仓库指令、plan/spec、直接关联决策、当前代码与测试。
- 记录仓库根、分支、HEAD、working tree;保留既有改动,不 reset / clean 无关内容。
- 给原始计划的每项工作标记:
| 状态 | 证据 |
|---|---|
VERIFIED_DONE | 当前代码与本轮可复现验证证明已交付 |
PENDING | 本次仍须实现或修复 |
OBSOLETE | 被有效决策或新契约取代,并引用来源 |
EXCLUDED | 用户或有效文档明确排除 |
HUMAN_DECISION | 尚无权威答案,且选择会改变产品行为、公共契约、数据归属、安全、冻结范围或需新增外部授权 |
冻结范围包含本轮全部 PENDING 及必要测试/文档。可按依赖顺序拆成内聚批次,但不得只完成第一个容易批次就声称 plan 已完成。
原始 PENDING 不能被 reviewer 建议偷换成 Backlog:Backlog 是 reviewer 对新发现的分类,plan 承诺项的归属只属于用户或有效决策。它只能完成、被有效决策取代、明确排除或进入 HUMAN_DECISION。
可逆、范围内、不改变已决定行为的实现细节与测试选择仍属于对应 PENDING,不是 HUMAN_DECISION。按权威文档、当前代码、仓库惯例、最小改动和验证质量自行决定;agent 意见不一致本身不构成门禁。
正式 evidence id 采用 agentic-review-handoff 返回的 evidence 对象,相等性只比较 baseSha + pathFilter + digest。优先复用依赖 skill 的冻结证据,但每道门禁前后必须用同一 base/filter 执行 review-loop evidence 重算;相同 HEAD 或相同 git status 不等于相同快照。任何范围内代码或测试修改都会使旧快照的下游 test/review/audit 结论过期。
Phase 1:三方收敛与用户决策
A. 独立立场
宿主、真实 Peer A、真实 Peer B 分别读取同一组文档、代码和任务账本。每方写清范围、归属、假设、风险、排除项和可证伪验证。用 review-loop sessions 记录两个 Peer 的可恢复句柄;本步首条成功往返同时完成预检第 2 项。
预算与并行
- A 的三方立场互不依赖:宿主写自己的立场时,并行发起 Peer A 与 Peer B。
- B 的两次交叉质疑互不依赖,并行发起。B 至多两轮;第二轮后仍存分歧,属技术默认值由宿主依证据裁定,属用户决策转入 C。
- 每次外部调用设 deadline(默认与
agentic-review-handoff的 Reviewer timeout 一致,20 分钟;宿主可缩短并记录)。以后台进程发起并按下一条等待,避免宿主前台工具超时截断真实会话。进程存活时不杀、不重发;超时先由--fallback换人(见「Peer 选择」),没有可换的才按DELIVERY_UNKNOWN处理:仅当本地证据证明未提交才同参数重试一次,否则本阶段记UNVERIFIED,保留句柄与已得立场,下一轮从缺失的一方继续。 - 等后台外部调用结束:优先等发起时记下的 PID(如
review-loop consult ... > out 2>&1 & echo $! > pid,再while kill -0 "$(cat pid)" 2>/dev/null; do sleep 15; done),或用宿主自带的后台任务完成通知。不用pgrep -f/ps | grep按等待命令自身也含的字符串轮询:它会匹配到等待脚本自己,循环永不结束;非用模式不可时写成[r]eview-loop这类方括号形式,让它匹配不到自身。 - 快路径:账本无
HUMAN_DECISION、范围由 plan/代码唯一确定、A 三方在范围/归属/验证上无实质分歧时,B 只跑一轮,无新分歧即收敛。快路径不减少参与方,不省略 B。
B. 交叉质疑
- 把宿主 + Peer B 立场交给 Peer A;把宿主 + Peer A 立场交给 Peer B。
- 双方攻击对方最强论点,并允许依据证据改口。
- 宿主独立打开引用路径、核对当前行为,再综合证据。
三份平行评论不算收敛:只有被对方攻击过仍成立的论点才是证据。
C. 用户决策
- 权威文档和代码已经给出答案,或只剩普通技术默认值:自行收敛,不重新提问。
- 真正的
HUMAN_DECISION:用户说“不要问”也不扩大产品决策或外部写授权(见「入口与授权」);Agent 一致不能代替用户。 - 出现真实用户决策或显式
grill-with-docs时,先读 decision-and-terminal-gates.md 的 Human decision convergence,再决定是否返回HUMAN_GATE。按 grilling 的 frontier round 提问:同轮可含全部互不依赖的问题,每个问题都附推荐答案,让用户只做取舍而不重新调研。
记录:
Three-party Convergence
- Decision:
- Why:
- Work ledger:
- Frozen scope / exclusions:
- Ownership and dependency direction:
- Verification:
- Peer A (product) session:
- Peer B (product) session:
- Fallbacks: none | <from → to, reason>
- Remaining decisions: none | <list>
Phase 2:Goal Gate
收敛后调用 goal-gate,严格服从其 Decision / Next:
wait for user /goal、ask approval或defer:返回HUMAN_GATE并停止。生成 prompt 不代表 Goal 已激活。suggest+adopt goal and continue:按 transcript contract 继续本 Loop,报告Goal: not-created;suggest+provide prompt/route elsewhere:返回HUMAN_GATE。- 已有 Goal:从 native 工具、产品状态或调用方传入的可核对 parent contract 比较 objective、冻结范围、Done condition 与 completion owner;native getter 不是唯一证据源。ownership 关系与完成权见 decision-and-terminal-gates.md 的 Goal ownership;冲突或证据不足才
defer。 - 可激活或采用时,Goal 覆盖任务账本、冻结范围、验证、三道门禁、协议写和外部写边界。
Done condition 要求:账本无 PENDING / HUMAN_DECISION;验证和三道门禁覆盖同一最终 evidence id。只有 created-by-loop / exact-same-goal 由本 Skill 完成;broader-compatible 即使本 Loop 已完成,也保持父 Goal active,并报告 Goal: active-checkpoint。
Phase 3:实现与验证
按依赖顺序处理全部 PENDING:
- 转成可观察成功标准;行为变更可行时先展示失败复现。
- 做最小内聚改动,不顺手做相邻 backlog 或投机抽象。
- 先跑定向检查,再跑相关包/仓检查。
- 对外可见行为使用浏览器、CLI、日志、渲染或请求/响应等真实 runtime 信号。
- 证据通过后才标记
VERIFIED_DONE,并同步 plan / 现状文档。
未运行、失败或已过期的必需证据记 UNVERIFIED,不能算通过。
Phase 4:三道门禁
开始或恢复本阶段前,读 decision-and-terminal-gates.md 的三份 terminal contract;依赖拥有内部状态机,本 Skill 只核对终态、evidence id 和父 Goal ownership。
agentic-review-handoff:默认completion=pass;只在最终PASS/NO_FINDINGS覆盖当前 evidence id 时继续。BLOCKED、concerns_require_fix、review-only 与异常路径见 reference。architecture-hardening-loop:同范围运行,只接受NO_ACTIONABLE_FINDINGS;其HUMAN_GATE/MISSING_DEPENDENCIES/UNVERIFIED原样透传为本 Loop 的同名 Result。它修改文件会使旧 evidence id 失效;其内部 review 覆盖最终 evidence id 时可复用,不必重跑直接 review。Fix 与 ownership 路径见 reference。- 全新 Claude 盲审:使用新的可验证只读会话审最终 evidence id。范围内
Fix触发最小修复和全部下游门禁重跑;最多 2 轮。
无人值守续跑
仅用于无人值守 / 自主运行;有人在场回答的 human-in-the-loop 会话不套用。
- 纯文本结束的回合是进度报告,不是完成证据。任务账本就是 checklist,每回合更新;回合结束时仍有
PENDING且未写明 blocker,就继续,或由宿主 / 父会话发一条点名未完成项的短消息。同一任务自动续跑最多 2–3 次,之后停下交审(按下文预算规则返回UNVERIFIED),让真正卡住的运行结束。 - 本 Loop 启动的后台命令、subagent 或 Peer / Claude 会话仍在运行时,等它结束并取回输出,不把任务当作完成。
- 不应出现的提前停止:(1) 长总结只宣布下一步、没有工具调用;(2) 提出“除非你另有安排,否则我继续”并等回复;(3) 列出待用户决策项,但按自己判断没有一项阻塞剩余工作;(4) 因回合太长或某个里程碑完成而停下汇报。状态说明与建议放在下一次工具调用的同一消息里。应当停止:没有用户就无法推进(
HUMAN_GATE),或阻塞点是被刻意保护的对象。本节不替代高风险 / 破坏性动作的确认,也不扩大「入口与授权」。
终态与报告
| Result | 使用条件 |
|---|---|
COMPLETED | 账本无未决项;必需验证通过;三道门禁覆盖同一最终 evidence id;最终盲审无范围内 Fix;owned Goal 已完成,或 parent Goal 保持 active-checkpoint |
HUMAN_GATE | 等待用户拥有的产品/领域决策、Goal 激活/冲突、权限、凭证、外部状态、范围扩张,或显式 review-only 决策 |
MISSING_DEPENDENCIES | 预检缺少始终要求或本轮实际需要的能力;源码尚未修改 |
UNVERIFIED | 实现可能存在,但必需证据未运行、失败或已过期;或外部会话 DELIVERY_UNKNOWN / 超时导致本轮立场、复审或审计证据缺失(保留句柄,下一轮从缺失方继续);Goal 不得完成 |
Phase 1 的 deadline、B 轮数与 Phase 4 的 2 轮盲审是本 Skill 的全部预算。预算见底既不是完成理由,也不是用户决策:它不改变代码是否正确,用户也无实质取舍可做。宿主可续跑时继续;必须交还控制时返回 UNVERIFIED、保持 Goal active,并从未完成证据继续,不要求用户重复授权。
跨任务经验
经验目录:${AGENT_LESSONS_DIR:-$HOME/.local/state/agent-lessons}/task-completion-loop/,每条一个 <slug>.md。它在 skill 目录外,更新 skill 不会覆盖,也不会进仓库。
- Phase 0 读仓库指令后,列出该目录,只读 cue 与本任务形态相符的条目。经验只是提示;与当前代码、证据或用户决策冲突时,以后者为准。
- 终态报告前,最多写一条新经验,三项缺一不写:
cue:遇到什么形态的情况适用。写情况的形状,不写本仓库的文件名、函数名或业务事实。lesson:这次学到什么做法或坑。evidence:哪个 evidence id、门禁或盲审结论证明它,以及对比的是哪两种做法。
- 只因结果
COMPLETED不构成经验;没有可对照的证据就不写。与已有条目重复时更新那条,不新增。 - 经验文件不得写入评审打分、凭证或用户私有数据。
Task Completion Result
- Scope / exclusions:
- Work ledger:
- Three-party decision:
- Goal: <completed | active-checkpoint | not-created | deferred-conflict>
- Final evidence id:
- Implemented:
- Verification:
- Agentic review: <packet/session + evidence id>
- Architecture hardening: <result + evidence id>
- Final Claude audit: <fresh session + evidence id>
- Fixed / Backlog / Rejected:
- Protocol, Git, and external actions:
- Lessons: <读取的条目 | 新写或更新的条目 + evidence | none(理由)>
- Result: COMPLETED | HUMAN_GATE | MISSING_DEPENDENCIES | UNVERIFIED
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |