本文件定义平台无关的命令语义。具体清单和薄提示词位于 commands/manifest.json 与 commands/prompts/。Claude Code、Codex、Gemini CLI 或其他宿主可以把它映射为斜杠命令、Skill 参数或自然语言；不得复制一套独立流程。
| 命令 | 层级 | 作用 | 门控 |
|---|---|---|---|
plan |
核心 | 根据当前讨论生成或更新 Plan；首次需要持久化时创建 .loop-flow/ |
不实施；更新递增 plan_version 并保留旧版 |
annotate |
核心 | 展示待答批注，吸收用户选择/other，生成新 Plan 版本并报告剩余缺口 |
不改变批准状态 |
ready |
核心 | 执行 Schema、语义和批注门检查 | 只读；ready_for_approval 不等于批准 |
approve |
核心 | 记录用户明确批准 | 必须用户确认；仅在策略要求时校验指纹 |
spec |
晋升后 | 从已批准完整 Plan 编译并冻结 Cycle Spec | Plan 未批准、批注未关闭或指纹/版本过期时拒绝；幂等返回 |
run [WU-id|--step|all] |
核心 | 执行已冻结合同，默认执行 all；Tier 1 执行已批准任务卡 |
完整模式需冻结 Spec，Tier 1 需批准任务卡；单步不能跳过 Review、测试或安全门 |
status |
核心 | 查看 Plan、周期、阻断和最近 Evidence 摘要 | 只读，不回显完整 Prompt/transcript |
validate |
核心 | 执行 Schema、引用、依赖、批注和指纹校验 | 只读；缺少校验器时诚实标记降级 |
resume |
恢复 | 从中断、checkpoint 或 blocked 状态继续 |
重新检查范围、批准和能力边界 |
retro |
收尾 | 用户显式触发独立高级 Consumer/Judge，分析 Trace 并提出优化候选 | 周期结束只提醒不自动执行；需用户显式调用和批准 |
cancel |
生命周期 | 取消当前 Plan 或周期 | 保留全部历史，不删除失败证据 |
plan不是“收到请求就直接生成”。主对话先进行必要讨论，再生成可带未决annotations的 Plan 初稿。annotate可以在同一命令中展示问题和吸收回答；只要必填批注仍为open/answered，就不能进入ready_for_approval。approve永远是用户动作。Tier 1 默认不需要指纹；晋升、不可逆效果或返工冻结时，使用python scripts/validate.py --fingerprint-plan <plan.json>计算并校验。- 完整模式的状态转移是
approve -> spec -> run：approve签署意图，spec冻结可执行合同，run只执行已冻结合同。Tier 1 通过批准任务卡后可直接run。 spec必须运行完整交叉校验；已有 Spec 指纹一致时不重复编译，Plan 版本或指纹变化时保留旧 Spec 并生成新的冻结版本。run遇到陈旧 Spec 才拒绝执行并要求重新运行spec。run --step只用于调试或恢复一个已授权步骤，不能改变既定 Review 顺序、跳过测试或扩大路径。validate失败返回revise、planning_review或blocked，不能包装成done。
dispatch、code-review、spec-review、build、test、audit 和 trace 是 run 的内部阶段；compile-spec 由用户可见的 spec 命令承载。宿主可为排障提供别名，但别名必须转发到本契约，不能另建状态机。
- Claude Code：可用
/loop-flow plan、/loop-flow spec、/loop-flow run等 Skill 参数；也可继续自然语言触发。 - Codex：可用
$loop-flow加命令参数或自然语言。 - Gemini CLI：使用其 Skill 发现和命令入口映射。
- 其他宿主：至少保留
plan、annotate、approve、spec、run、status、resume的自然语言降级。