| name | flow-long-task |
| description | Use when retikz work is a large, long-running, batch, multi-commit, or context-compaction-prone task that needs a durable execution reference, staged commit review, and final whole-change review. |
长任务总入口
面向会跨多轮上下文、批量执行或产生多次 commit 的任务。它只负责编排、恢复和 review gate;具体实现仍分流到 flow-alpha / flow-beta / flow-rc / develop-refactor / package-publish 等 skill。
启动关卡
执行前先确认:
- 任务 source of truth:Alpha 功能的长期契约用 ADR,执行用其 ignored 镜像
PLAN.md / TEST_CONTRACT.md;非功能重构用 superpowers:writing-plans 产出的 plan;Beta / RC / 发布用 roadmap、plan 或发布清单。
- 是否允许批量执行、是否允许 LLM 分步 commit。
- Architecture / Plan Gate 使用根规则的常驻只读授权;其它批量自动 commit 前 review、最终整体 review 先按根规则判定风险,再确认所需授权。
- 临时状态文件位置。Alpha 必须使用 ADR 的
**/_notes/plans/ 镜像目录;其它任务使用 .gitignore 覆盖的 notes/plans/ 或就近 **/_notes/plans/。
未确认 source of truth 前不改代码;Alpha 必须在 Architecture Gate、人工 ADR 确认、镜像 plan 与 Plan Gate 均通过且已有实现授权后执行。未授权 commit 前不 commit;常驻 Gate 之外未授权 subagent / 外部模型前不调度 review。
分流
- 功能迭代:读
flow-alpha,再按 ADR 阶段读取 develop-design / develop-implement / develop-test / develop-document / develop-wrapup。
- 非功能重构:读
develop-refactor,plan 作为执行参考。
- beta / rc:读
flow-beta / flow-rc。
- 发布:读
package-publish。
- 涉及分层、schema、contract、providers、pipeline、compile 时,按
standard-structure 读取对应 standard-*。
状态文件
为防上下文压缩失忆,长任务必须维护 ignored 状态文件。Alpha 使用镜像 plan:
packages/<group>/_notes/decisions/<relative>/<NN>-<slug>.md
-> packages/<group>/_notes/plans/<relative>/<NN>-<slug>/TASK_STATE.md
# 非 ADR 长任务
notes/plans/<task>/TASK_STATE.md
状态文件至少包含:
- 目标、非目标、source docs、当前阶段。
- 文件 scope、分步计划、commit 切分。
- 已完成 commit、验证命令、review 结论。
- 人工裁决、阻塞点、风险和下一步。
- 恢复指令:下一轮先读哪些文件、从哪一步继续。
每次 commit 后、停止前、预计可能压缩前都更新。状态文件默认不 stage / commit;不要把文件索引、LLM 执行 checklist、review prompt 等临时材料塞进最终 ADR。
恢复流程
上下文恢复或接手长任务时,按顺序读取:
- 根
AGENTS.md 与本 skill。
- source docs:ADR / roadmap / 发布清单。
- reviewed
PLAN.md、TEST_CONTRACT.md、TASK_STATE.md、REVIEW.md;不适用的文件跳过。
git status --short、最近 commits、当前 staged diff。
- 本阶段需要的具体 flow / develop / standard skill。
恢复后先复述当前阶段、下一步和风险;发现状态文件与 git 不一致时 halt,先对齐事实。
Commit 前 Review
用户批准批量执行并授权 LLM 自行 commit 时,先逐 commit 判定风险。改动面大、核心能力、公开契约、跨包边界或高风险 commit 必须单独过 gate;非 ADR、scope 明确且仅涉及文档、文案、链接、格式或机械性调整,并且不改变公开契约、schema、runtime 行为或跨包边界时,可跳过 subagent review 并在 TASK_STATE.md 记录理由。其余情况按根规则询问用户。需要 review 时:
- 只 stage 本 commit 文件,不用
git add -A。
- 跑受影响验证;验证失败不进入 review。
- 按
cross-review 冻结 staged diff,同轮并发派发 2–3 个 fresh 独立 reviewer;优先不同模型,只有一个非主模型时使用两个同模型 fresh 实例。
- 主 AI 收齐同轮结果后归并;修复 BLOCKING 后冻结新 staged snapshot,用 fresh agents 复审。WARNING 需要人工裁决或记录理由。
- commit 成功后更新
TASK_STATE.md。
Review 输入只给:长期 ADR / source doc、reviewed plan、相关 AGENTS / standard skill、staged diff、验证结果。所有模型得到相同输入,同轮互不可见结论;不要传主 AI 的预判。
Review 固定检查:
- 文件结构、依赖方向、分层位置是否符合就近 AGENTS 和
standard-structure。
- 命名是否符合项目规则;barrel 是否默认
export *,避免无必要的 export { ... } 聚合。
- 导出类型、接口、函数、组件、重要 helper、public props、复杂字段的 JSDoc 是否完备。
- 注释 / JSDoc 是否中文;Zod
.describe(...) 是否英文契约描述。
- 是否偏离 ADR / plan、混入额外目标、弱化测试或漏同步 docs。
Review 输出只分:
BLOCKING:必须修或人工裁决后才能 commit。
WARNING:可由人工裁决或记录风险。
INFO:可选建议。
每个 commit review 最多 9 轮。最新一轮至少两个 fresh 独立 reviewer 完成、无 BLOCKING、WARNING 已裁决时立即 PASS,不再追加下一轮;只有修订后才使用 fresh agents 复审。无法完成两个 fresh 独立 reviewer、快照漂移或第 9 轮未通过时 halt,交人工决策。
最终整体 Review
全部实现完成后,先按根规则判定整体 review 风险;低风险明确改动可跳过并记录理由,需要 review 时再按用户授权和 cross-review 对固定完整 working-tree diff 或 commit range 并发派发 2–3 个 fresh 独立 reviewer,并由 cross-review 选择异模型优先或同模型双实例降级阵容。没有 commit 授权时使用 working-tree diff,不得为了整体 review 提前 commit;已有多个 commit 时使用固定 range。输入包含 ADR / source docs、reviewed plan、TASK_STATE.md、commit list(如有)、完整 diff 与验证结果。
整体 review 检查:
- source docs 与最终实现、测试、docs / changelog 是否一致。
- 多 commit 间是否命名漂移、结构不一致、重复抽象或 public surface 漏迁移。
- 是否有遗漏的
standard-* 约束、JSDoc、中文注释、barrel 规则。
- 验证范围是否足够;是否需要补测或扩大到跨包验证。
最终 BLOCKING 清空后,再进入 wrapup、roadmap / ADR 状态更新或交付汇报。
整体 review 同样按轮次归并;当前轮无 BLOCKING、WARNING 已处置时立即 PASS。只有修订后才使用新的完整 working-tree diff 或 commit range 与 fresh agents 进入下一轮,最多 9 轮;第 9 轮仍未 PASS 时交人工。不得串行把一个模型的结论喂给同轮其它模型。
失败与暂停
- ADR / plan 自相矛盾、scope 膨胀、git 状态不明、连续 3 轮验证失败、第 9 轮 review 仍有 BLOCKING:halt,汇报事实和选项并交人工决策。
- 不 push / tag / publish;这些始终需要单独授权。
- 不提交临时 plan、状态文件、review 报告,除非用户明确要求转为正式文档。