<用途>
Ultragoal 将概要拆解为一组有序的目标，在持久化追加式账本中记录开始/检查点/阻塞器/失败事件，并告知当前 Claude 代理如何配合计划驱动 Claude Code /goal 斜杠命令。它不能——也无法——从 shell 修改 Claude /goal 状态；它只持久化仓库级状态并打印模型可读的交接文本，当前代理必须在会话内据此行动。
</用途>
<使用时机>
- 用户希望跨多个 Claude 会话或工作树持久化追踪一个 ultragoal
- 任务规模较大，需要多个有序的“故事（story）”，并附带尝试次数和每个故事的证据
- 用户希望最终完成需要通过 ai-slop-cleaner + 验证 + $code-review 的门控
- 用户希望将当前 Claude
/goal指令与账本协调一致，以便会话重启时不会丢失进度 </使用时机>
<请勿使用时机>
- 任务是一次性小改动——请改用直接委托或
ralph - 用户希望代理从 shell 直接调用
/goal——这是不可能的；omc ultragoal仅写入制品并打印交接文本 - 用户只需纯计划制品且不包含执行循环——请改用
plan</请勿使用时机>
<为什么存在>
Claude Code 的 /goal 是一个会话级停止钩子：它会阻止会话停止直到条件满足，并在成功时自动清除。这是一个出色的单会话执行原语，但它会跨会话丢失状态，并且本身不强制执行最终审核门控。omc ultragoal 添加了持久化计划、账本和门控层，使得长周期、多步骤的任务能够在会话重启、全新工作树和审核迭代后仍然存活，同时仍然利用 Claude /goal 保持当前代理的聚焦。
</为什么存在>
<如何使用>
-
从概要创建计划：
omc ultragoal create-goals --brief-file plan.md或使用显式故事：
omc ultragoal create-goals --brief "ship the migration" \ --goal "Schema::添加新列" \ --goal "Backfill::分批回填行" \ --goal "Cutover::删除旧列并切换读取"默认模式为
aggregate（一个 Claude/goal覆盖整个运行）。 如果希望每个故事拥有自己的/goal，请传递--claude-goal-mode per-story。多仓库工作区/并行会话： 当同一工作区中的多个 Claude 会话需并发运行
/ultragoal时，请传递--plan-id <稳定ID>或--auto-plan-id，这样计划会被写入.omc/ultragoal/plans/{planId}/而非共享的单计划路径。 如果不加此参数，同时创建目标的两个会话会互相覆盖。--auto-plan-id会根据概要标题派生{epochMs}-{slug}。之后在同一个会话中的所有后续子命令中传入相同的--plan-id <id>。 需要时，可使用omc ultragoal list-plans列出可用的 planId。 -
开始（或恢复）下一个故事：
omc ultragoal complete-goals [<goal-id>]不加 goal id 时，保持默认行为：恢复当前活跃故事，或开始第一个待处理故事。指定 goal id 时，OMC 精确瞄准该命名资格故事（挂起的故事可按任意顺序开始）；它绝不会回退到另一个故事。如果存在另一个活跃故事、未知 id、已完成或审核阻塞的故事，或未使用
--retry-failed的失败故事，则拒绝且不修改状态。指定的进行中故事会被恢复而不更改其尝试次数。此命令会打印模型可读的交接文本。当前 Claude 代理必须阅读该文本并：- 为此会话设置原生 Claude
/goal——在独立的 Claude Code 中，shell 和代理都无法执行此操作，因此请要求用户输入/goal <总体目标>并等待。--claude-goal-json（见下文）仅协调账本，不满足 PreToolUse/goal守卫，该守卫在观察到活跃的/goal之前会阻止工具调用。 - 执行故事。
- 当故事完成（并且对于最终故事，通过完整质量门控后），分享当前活跃
/goal状态的快照并调用checkpoint。
- 为此会话设置原生 Claude
-
检查点化一个故事：
omc ultragoal checkpoint --goal-id G001-... --status complete \ --evidence "tests/files/PR evidence" \ --claude-goal-json '{"goal":{"objective":"...","status":"active"}}'对于最终故事，还需传递
--quality-gate-json，包含aiSlopCleaner、verification和codeReview证据（全部为干净状态）。 -
如果最终审核不干净，请勿标记完成。记录阻塞器：
omc ultragoal record-review-blockers --goal-id G00X-... \ --title "解决最终代码审查阻塞器" \ --objective "修复列出的审查发现项并重新运行最终门控" \ --evidence "<审查发现项>" \ --claude-goal-json '{"goal":{"objective":"...","status":"active"}}'这会追加一个新的阻塞故事，并保持 Claude
/goal处于活跃状态。 -
随时检查状态：
omc ultragoal status
</如何使用>
<重要限制>
- Shell 不能调用或修改 Claude Code
/goal状态。omc ultragoal仅持久化制品并打印当前 Claude 代理需要读取并在会话内行动的手册。 - 通过
--claude-goal-json传递的快照是模型提供的活跃/goal状态证明；OMC 会验证其文本内容是否与计划的预期目标和账本事件一致，但无法独立观测 Claude/goal状态。这些快照不满足 PreToolUse/goal守卫，该守卫要求实际存在一个活跃的/goal——无论是主机注入的快照还是用户会话内设置的原生/goal。 - 如果 Claude
/goal斜杠命令被重命名或重构，只需要更改交接措辞；协调逻辑与名称无关。 </重要限制>
并行会话注意事项
- 多仓库工作区锚点： 在父目录放置一个
.omc-workspace标记文件，使多个跨子仓库的会话共享同一个.omc/。解析顺序：OMC_STATE_DIR > .omc-workspace > git > cwd。参见docs/REFERENCE.md。 - 会话 ID 来源： 在 CLI 上下文中
OMC_SESSION_ID环境变量优先；在钩子上下文中data.session_id有效载荷优先。 - 计划 ID（适用时）： 同一工作区中的两次运行会因共享计划制品而产生冲突。请使用不同的会话 ID（钩子有效载荷的 session_id 已按每个 Claude Code 会话隔离），或传入
--plan-id以保持并行 ultragoal 运行在不同的账本上。 - 并行结论： 支持（每个会话写入自己的会话级状态）。