ultragoal

Ultragoal 会将简要描述拆解为一组有序目标，在持久化的仅追加日志中记录开始、检查点、阻塞和失败事件，并告知当前 Claude Agent 如何将 Claude Code `/goal` 斜杠命令与计划配合使用。它不会也无法从 shell 修改 Claude `/goal` 状态；它会持久化仓库状态，并输出面向模型的交接信息，由当前 Agent 在会话中执行。

<Use_When>

• 用户希望通过持久化、原生于仓库的方式，跨多个 Claude 会话或工作树跟踪 ultragoal
• 工作规模足以拆分为多个有序的“故事”，并跟踪尝试次数和每个故事的证据
• 用户希望最终完成必须经过 ai-slop-cleaner、验证和 $code-review
• 用户希望协调当前 Claude /goal 指令与日志，避免会话重启导致进度丢失 </Use_When>

<Do_Not_Use_When>

• 任务只是单个小改动——改用直接委派或 ralph
• 用户希望助手直接从 shell 调用 /goal——这是不可能的；omc ultragoal 只会写入工件并输出交接文本
• 用户只想要规划工件，不需要执行循环——改用 plan </Do_Not_Use_When>

<Why_This_Exists> Claude Code /goal 是一个会话范围的 Stop 钩子：只要条件尚未满足，它就会阻止会话停止，并在成功时自动清除。这是一个很好的单会话执行原语，但它无法跨会话保留状态，也不会自行强制执行最终审查关卡。omc ultragoal 增加了持久化计划、日志和关卡，使长期、多步骤的工作能够在会话重启、新建工作树和审查迭代期间继续推进，同时仍可借助 Claude /goal 让当前 Agent 保持专注。 </Why_This_Exists>

<How_To_Use>

在 omc 不在 PATH 中的纯插件安装环境下，请将以下命令和生成的交接信息中的 omc 前缀替换为 oh-my-claudecode.js，或使用 node <plugin-root>/bin/oh-my-claudecode.js。

1. 根据简要描述创建计划：

   omc ultragoal create-goals --brief-file plan.md
   

   或显式指定故事：

   omc ultragoal create-goals --brief "ship the migration" \
     --goal "Schema::Add new columns" \
     --goal "Backfill::Backfill rows in batches" \
     --goal "Cutover::Drop old columns and switch reads"
   

   默认模式为 aggregate（一个 Claude /goal 覆盖整个执行过程）。 如果希望每个故事都有自己的 /goal，请传入 --claude-goal-mode per-story。

   **多仓库工作区／并行会话：**如果同一工作区中的多个 Claude 会话需要并发运行 /ultragoal，请传入 --plan-id <stable-id> 或 --auto-plan-id，这样计划就会写入 .omc/ultragoal/plans/{planId}/，而不是共享的单计划路径。 如果不传此标志，两个会话创建目标时会相互覆盖。 --auto-plan-id 会根据简要描述标题生成 {epochMs}-{slug}。随后，在该会话的每个子命令中都传入 相同的 --plan-id <id>。 必要时使用 omc ultragoal list-plans 枚举可用的 planId。

2. 开始（或恢复）下一个故事： ``` omc ultragoal complete-goals [] ``` 不指定目标 ID 时，将保留默认行为：恢复当前活动故事，或开始第一个待处理故事。指定目标 ID 时，OMC 将精确定位到该名称对应的符合条件的故事（待处理故事可以不按顺序开始）；绝不会转而处理其他故事。若存在另一个活动故事、ID 未知、故事已完成或因审核而受阻，或者故事失败但未指定 `--retry-failed`，则会拒绝操作且不更改状态。若指定的故事正在进行中，则会恢复该故事，且不更改其尝试次数。这会输出一份面向模型的交接说明。当前活动的 Claude Agent 必须阅读并执行以下操作： - 为本次会话设置原生 Claude `/goal`——在独立运行的 Claude Code 中，shell 和 Agent 都无法设置，因此需请用户输入 `/goal ` 并等待。`--claude-goal-json`（见下文）仅用于协调账本，不满足 PreToolUse `/goal` 防护条件；该防护会在检测到活动的 `/goal` 之前阻止工具调用。 - 完成该故事。 - 故事完成后（对于最后一个故事，则需在完整质量门禁通过后），分享活动 `/goal` 状态快照，并调用 `checkpoint`。

3. 检查点记录故事：

   omc ultragoal checkpoint --goal-id G001-... --status complete \
     --evidence "tests/files/PR evidence" \
     --claude-goal-json '{"goal":{"objective":"...","status":"active"}}'
   

   对于最后一个故事，还需传入包含 aiSlopCleaner、verification 和 codeReview 证据（均无问题）的 --quality-gate-json。

4. 如果最终审核未通过，不要标记为已完成。记录阻塞项：

   omc ultragoal record-review-blockers --goal-id G00X-... \
     --title "Resolve final code-review blockers" \
     --objective "Fix the listed review findings and rerun final gates" \
     --evidence "<the review findings>" \
     --claude-goal-json '{"goal":{"objective":"...","status":"active"}}'
   

   这会追加一个新的阻塞故事，并保持 Claude /goal 处于活动状态。

5. 随时检查状态：

   omc ultragoal status
   

</How_To_Use>

<Important_Limitations>

• shell 无法调用或更改 Claude Code 的 /goal 状态。omc ultragoal 只会持久化可靠的工件，并打印说明，供当前会话中的活动 Claude Agent 阅读并执行。
• 通过 --claude-goal-json 传入的快照是由模型提供的活动 /goal 状态证明；OMC 会验证其文本是否与计划预期目标和账本事件一致，但无法独立观测 Claude 的 /goal 状态。它们不满足 PreToolUse /goal 防护条件；该防护要求实际存在活动的 /goal——由宿主注入的快照，或用户在会话中设置的原生 /goal。
• 如果 Claude /goal 斜杠命令被重命名或重构，只需更改交接说明措辞；协调逻辑与名称无关。 </Important_Limitations>

并行会话注意事项

• **多仓库工作区锚点：**在父目录中放置 .omc-workspace 标记，以便多个跨子仓库的会话共用一个 .omc/。解析顺序：OMC_STATE_DIR > .omc-workspace > git > cwd。参见 docs/REFERENCE.md。
• **会话 ID 来源：**在 CLI 上下文中，OMC_SESSION_ID 环境变量优先；在 hook 上下文中，hook 负载数据中的 session_id 优先。
• **计划 ID（适用时）：**同一工作区中的两次运行会在共享计划工件上发生冲突。请使用不同的会话 ID（hook 负载中的 session_id 已按 Claude Code 会话隔离），或传入 --plan-id，使并行的 ultragoal 运行使用不同账本。
• **并行判定：**支持（每个会话都会写入各自会话范围内的状态）